Responses and errors

Every response — success or failure, every endpoint — has the same four keys.

Success

{
  "status": true,
  "message": "OK.",
  "data": { "id": "a742a438-...", "name": "Asha Menon" },
  "error": null
}

data is the part you want. message is for humans and is not a stable contract — never branch on its text.

Failure

{
  "status": false,
  "message": "This phone number is already in use.",
  "data": null,
  "error": {
    "detail": "This phone number is already in use.",
    "errors": {
      "phone": ["This phone number is already in use."]
    }
  }
}

On failure status is false and data is null. error.detail is always present; error.errors appears on validation failures and maps each field name to a list of messages — always a list, even for a single message.

Branch on the HTTP status code, and read error.errors for field-level problems.

Status codes

Code	When
`200`	Read, update, delete, or an action that completed.
`201`	Something was created — including `POST /calls/dispatch/`, which creates a call log.
`400`	Validation failed. Check `error.errors`.
`401`	Bad, missing, expired or revoked key.
`403`	Authenticated, but the key lacks the scope — see Scopes.
`404`	No such record, or it belongs to another organization.
`429`	Rate limited. Back off and retry.
`5xx`	Our problem. Safe to retry idempotent reads; be careful retrying a dispatch.

Rate limits

Requests are limited per key, with a shared counter across our servers, so a burst from several of your workers counts once against the same budget. Exceed it and you get 429. The exact rate is environment-specific — assume a few hundred requests an hour unless you have been told otherwise, and back off rather than tuning to a number that may change.

A note on 404 vs 403

Asking for a record belonging to another organization returns 404, not 403. This is deliberate: a 403 would confirm the record exists, which is a way of enumerating other customers' data. If you are certain an id is right and still get 404, check you are using the key for the right organization.