Error handling

The API uses standard HTTP status codes. Every 4xx response returns a JSON body with an error field and, in most cases, a suggestion field:

{
  "error": "Receptionist not found",
  "suggestion": "List receptionists with GET /api/v1/receptionists and use a returned id."
}

error is a human-readable message. suggestion is an optional imperative fix. If you are building an AI agent, have it read suggestion before asking the user for help; it usually says exactly how to fix the request.

Status codes

Code	Meaning	What to do
400	Bad request (missing or invalid parameters)	Fix the request per the suggestion and retry.
401	Invalid or missing API key	No retry will help. Check the Authorization header.
403	Scope required but not granted on the key	Get a key with the needed scope. See API keys and scopes.
404	Resource not found, or belongs to another account	Verify the id. See the note on tenant isolation below.
409	Conflict (for example, the plan receptionist limit is reached)	Free the conflicting resource or contact support to raise the cap.
422	Unprocessable (for example, the recipient opted out of SMS, or the receptionist is not active)	Do not retry as-is. An opt-out 422 means skip that contact; it cannot be overridden.
429	Rate limited	Read the Retry-After header and wait. See Rate limits.
5xx (500, 502, 503)	Server error, upstream service error, or temporary unavailability	Retry with exponential backoff and the same Idempotency-Key. See Idempotency.

404 and tenant isolation

A 404 is returned both when a resource does not exist and when it exists but belongs to another account. The API never confirms the existence of another tenant's resources, so treat 404 as "not visible to this key" rather than proof that an id was never issued.