Client behavior

Design clients around explicit failure modes.

Use conventional HTTP status codes, structured error bodies, request IDs, and retry budgets so failures are observable and safe to recover from.

Runtime APIBearer tenant keys

Admin APIx-admin-key

TelephonyTwilio signatures

SpecsOpenAPI 3.1

Status codes

Status	Meaning	Client action
`400`	Request validation failed.	Fix the request before retrying.
`401`	Missing, malformed, or expired credential.	Check bearer token, admin key, session cookie, or webhook signature.
`404`	The requested resource was not found.	Confirm identifier and tenant boundary.
`409`	The request conflicts with current state.	Reload current state and submit a new command.
`412`	A precondition did not match.	Fetch the latest version and retry with the current precondition value.
`429`	Rate limit blocked the request.	Back off with jitter and respect `Retry-After`.
`500` / `502` / `503`	Server or provider failure.	Retry only if the operation is safe or your workflow is idempotent.

{
  "error": "invalid_request",
  "message": "to must be a valid E.164 phone number",
  "details": {
    "field": "to"
  }
}

Retry 429, 500, 502, and 503 with exponential backoff and full jitter.
Do not automatically retry validation, authentication, authorization, or not-found failures.
For outbound calling, avoid duplicate calls unless the prior request definitively failed before scheduling.