Production clients should classify failures into operator actions.
Callaro non-2xx responses include error_code. Use both status and error_code to decide whether to retry, reconfigure, or escalate.
Operator response matrix
| Status | Example error_code | Typical endpoint families | Operator action |
|---|
| 401 | UNAUTHORIZED, JWT_REQUIRED | Any authenticated endpoint | Validate token/key, environment, and auth model |
| 403 | FORBIDDEN | Scoped key endpoints (campaigns, contacts, billing) | Grant missing scope or use correct key type |
| 404 | SESSION_NOT_FOUND, resource-specific not found | Voice sessions, contacts, campaign detail | Verify ID and tenant context |
| 422 | VALIDATION_ERROR, domain-specific codes | Create/update/launch operations | Fix payload/business preconditions and retry |
| 429 | Rate limit codes | High-volume list and mutation workloads | Backoff and throttle worker concurrency |
| 5xx | INTERNAL_ERROR | Any | Retry with capped backoff; escalate with request_id if persistent |
Retry policy guidance
- Retry: network failures, 429, and selected transient 5xx errors.
- Do not retry blindly: 401, 403, most 404, and structural 422 errors.
- Record
request_id for all failed requests.
curl "https://api.callaro.ai/api/v1/voice_sessions/999999" \
-H "X-Api-Key: $CALLARO_API_KEY"
Endpoint-family examples
- Campaign launch: 422 usually indicates missing contacts, schedule issues, or invalid campaign configuration.
- Contacts import/export: 422 often signals invalid CSV mapping or payload schema.
- Phone number purchase: 422 may indicate region/provider constraints.
- Billing allocation: 403/422 should be reviewed for partner scope and payload correctness.
Never classify all 4xx responses as permanent and all 5xx responses as safe retries. Use endpoint context and error code semantics to avoid duplicate side effects.
