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"

const response = await fetch('https://api.callaro.ai/api/v1/voice_sessions/999999', {
  headers: { 'X-Api-Key': process.env.CALLARO_API_KEY }
});
const payload = await response.json();
if (!response.ok) {
  const retryable = response.status === 429 || response.status >= 500;
  console.error({
    status: response.status,
    error_code: payload.error_code,
    message: payload.error,
    request_id: payload.request_id,
    retryable
  });
}

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.

Overview

Resource Guides

Generated Endpoints

Errors and Error Codes

Production clients should classify failures into operator actions.

Operator response matrix

Retry policy guidance

Endpoint-family examples

​Production clients should classify failures into operator actions.

​Operator response matrix

​Retry policy guidance

​Endpoint-family examples

Production clients should classify failures into operator actions.

Operator response matrix

Retry policy guidance

Endpoint-family examples