​

Production clients should classify failures into operator actions.

​

Operator response matrix

​

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.