Errors & troubleshooting
Understand API errors and choose a safe next step.
Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis
Error format
Errors handled by the call API use application/problem+json. Edge/proxy failures and unmatched routes or methods can use a different JSON shape or HTML; do not assume every failed response contains code. Inspect both the HTTP status and the machine-readable code; use detail for the explanation.
{
"type": "about:blank",
"title": "Live calls disabled",
"status": 403,
"detail": "This agent gateway does not permit live calls.",
"code": "live_calls_disabled"
}Status codes
- HTTP
- 400
- Code
missing_idempotency_key- Next step
- Provide a non-empty Idempotency-Key header.
- HTTP
- 401
- Code
invalid_api_key,api_key_revoked,api_key_expired- Next step
- Check the key or create a replacement in Settings.
- HTTP
- 402
- Code
insufficient_credits,insufficient_credits_for_call- Next step
- Ask the user to log in and recharge at action_url. The rejected request did not dial or charge call credits. Stop automatic retries; retryable is false.
- HTTP
- 403
- Code
live_calls_disabled,agent_project_inactive- Next step
- Calling is disabled for the service or project. Resolve the permission first.
- HTTP
- 404
- Code
call_not_found- Next step
- Check the call ID and use a key from the project that created it.
- HTTP
- 405
- Code
- May have no code field
- Next step
- Check the HTTP method. Creation is POST /v1/calls; GET /v1/calls is not a list endpoint.
- HTTP
- 409
- Code
idempotency_conflict- Next step
- Replay the original payload, or intentionally start a separate call with a new key.
- HTTP
- 409
- Code
managed_agent_unavailable- Next step
- Check that assistant setup is complete and the workspace assistant is active.
- HTTP
- 422
- Code
invalid_call- Next step
- Check required fields, phone format, result schema, task length, and limits.
- HTTP
- 429
- Code
rate_limit_exceeded- Next step
- Honor Retry-After and reduce request frequency.
- HTTP
- 502
- Code
control_plane_error,invalid_control_plane_response- Next step
- Read detail. This can represent policy, workspace, or calling-service failures, not only a temporary outage.
- HTTP
- 503
- Code
control_plane_unavailable- Next step
- The service could not be reached. Treat a create request as uncertain and retain its idempotency key.
| HTTP | Code | Next step |
|---|---|---|
| 400 | missing_idempotency_key | Provide a non-empty Idempotency-Key header. |
| 401 | invalid_api_key, api_key_revoked, api_key_expired | Check the key or create a replacement in Settings. |
| 402 | insufficient_credits, insufficient_credits_for_call | Ask the user to log in and recharge at action_url. The rejected request did not dial or charge call credits. Stop automatic retries; retryable is false. |
| 403 | live_calls_disabled, agent_project_inactive | Calling is disabled for the service or project. Resolve the permission first. |
| 404 | call_not_found | Check the call ID and use a key from the project that created it. |
| 405 | May have no code field | Check the HTTP method. Creation is POST /v1/calls; GET /v1/calls is not a list endpoint. |
| 409 | idempotency_conflict | Replay the original payload, or intentionally start a separate call with a new key. |
| 409 | managed_agent_unavailable | Check that assistant setup is complete and the workspace assistant is active. |
| 422 | invalid_call | Check required fields, phone format, result schema, task length, and limits. |
| 429 | rate_limit_exceeded | Honor Retry-After and reduce request frequency. |
| 502 | control_plane_error, invalid_control_plane_response | Read detail. This can represent policy, workspace, or calling-service failures, not only a temporary outage. |
| 503 | control_plane_unavailable | The service could not be reached. Treat a create request as uncertain and retain its idempotency key. |
Client signature blocked
A Cloudflare 403 with error 1010 or browser_signature_banned happens before the request reaches the call API. It is not an LLM safety decision.
Use a descriptive client header such as User-Agent: CleoDocs/1.0. The downloadable Python script already does this. If access is still blocked, give your operator the returned Cloudflare Ray ID.
Live calls disabled
403 live_calls_disabled means the public API’s live-call permission is off. It stops before LLM evaluation and does not create a call. Your operator must enable public API calling; repeatedly submitting the request will not change that setting.
An uncertain submission
For connection failures, timeouts, and ambiguous server errors, a call may already exist. Follow the idempotency recovery steps. If you already have a call ID, read or sync it instead of creating another. reconciling with submission_unconfirmed is an ongoing recovery state. cancel_requested with cancellation_unconfirmed requires confirmation of that existing call. For reconciliation_required, keep the ID and contact the operator; do not redial.