Error Responses
The Custodian Labs Platform API returns standard HTTP status codes. On error, the response body includes a detail field describing the problem.
Status Codes
| Status | Meaning |
|---|---|
400 | The request was malformed or a field was invalid. |
401 | The API key is missing, invalid, inactive, or not recognized. |
403 | The API key exists but cannot be used, such as an expired key. |
404 | The requested Custodian, app, or squad was not found, or is not accessible. |
422 | The request body failed validation. |
429 | The API key or account reached its token or request limit. |
5xx | The Platform API or an upstream service failed. Retry the request. |
Error Body
Errors return JSON in the following shape:
{
"detail": "Custodian not found"
}
Common Signatures
Missing API key
401 Unauthorized
X-API-Key: ...
{
"detail": "Invalid or missing API key"
}
Check that you are sending the X-API-Key header and that the key is active.
App or squad not found
404 Not Found
{
"detail": "Team app not found"
}
Confirm you are using the correct app_id or team_app_id and that the deployment belongs to your account.
Validation error
422 Unprocessable Entity
{
"detail": "An error with no further information"
}
Compare your request body with the examples on the Chat page.
Retries
The Platform API is reliable, but transient 5xx and network errors can occur. The Python SDK retries these automatically (default two retries). For raw HTTP calls, retry idempotent failures with a short backoff.