Understand API errors

Route-level errors

• 400 means an accepted route received a malformed header, query, reference value, or body. The same-origin complaint gateway returns uniform 404 for unsupported or malformed paths.
• 401 means a key is missing, malformed, unknown, expired, or supplied through ambiguous credential headers.
• 403 means scope, assignment authority, account state, or plan API access is unavailable.
• 404 protects missing or inaccessible account-scoped complaints and evidence without distinguishing the reason.
• 409 marks optimistic-version or idempotency identity conflicts; 416 rejects attachment Range requests; 422 marks invalid lifecycle transitions.
• 429 is a distributed complaint API limit and includes Retry-After. 503 means an authorization, repository, storage, or evidence-integrity dependency is unavailable.

Per-recipient send errors

• Results can include invalid_phone, sender_not_configured, sender_resolution_failed, template_not_found, template_rejected, template_sender_mismatch, and outside_customer_service_window.
• Other outcomes include rate_limited, meta_send_failed, consent restriction reasons, conversation_read_only_removed_number, persistence failures, and unknown_error.
• rate_limited currently appears in an individual direct-send result rather than as a route-level 429 response.
• Blocked and invalid broadcast recipients can be classified before any Meta send.

Error envelope

{
  "error": "Complaint changed; reload before continuing",
  "statusCode": 409,
  "requestId": "request-correlation-id"
}

Recover safely

• Correct permanent recipient, consent, sender, template, policy, or request errors before a new attempt.
• Back off explicit transient rate or provider failures with bounded jitter.
• Inspect every direct-send result even when the HTTP response succeeded.
• Do not automatically repeat a mutation after an unknown outcome; reconcile message or broadcast identities first.