Errors - ChatBridge

The error envelope

Every error response from /api/v1/ is a JSON object with a single top-level error key whose value is a human-readable string:

{
  "error": "Invalid or expired API key."
}

This is consistent across authentication failures, permission checks, throttling, not-found, and method-not-allowed responses — you can always read body.error for a displayable message.

Machine-readable codes

A few errors you are expected to branch on also carry a code next to error. Match on code, never on the message text, which may be reworded:

`code`	Status	Meaning
`trial_expired`	`403`	The workspace’s trial has ended and no paid plan is active. The API key is refused for every request, reads included, until a plan is chosen in the dashboard.
`monthly_limit_exceeded`	`429`	Returned only by `POST /api/v1/broadcasts/{id}/confirm/`: the broadcast needs more messages than are left in the organization’s monthly quota. Nothing is sent and the broadcast stays a draft (see below). Single messages (`POST /api/v1/messages/`) are never refused for quota.
`rpm_limit_exceeded`	`429`	The organization’s per-minute send limit was hit. Retry after the `Retry-After` interval.

{
  "error": "This workspace's trial has expired. Choose a plan to restore access.",
  "code": "trial_expired"
}

Errors without a listed code have no code key. A monthly_limit_exceeded refusal also carries the numbers behind it, so you can narrow the audience or prompt an upgrade without another request:

{
  "error": "This send needs 1,200 messages but only 350 of your 5,000 are left this month (resets Oct 01). Narrow the audience or upgrade your plan.",
  "code": "monthly_limit_exceeded",
  "calls_used": 4650,
  "calls_limit": 5000,
  "calls_remaining": 350,
  "calls_needed": 1200
}

A broadcast either fits in what’s left or isn’t sent at all; it is never sent in part. The monthly quota stops bulk sends only (broadcasts and sequences). Replies, including POST /api/v1/messages/, keep working at the cap and still count toward usage.

Status codes

Status	Meaning
`200 OK` / `201 Created`	Success. `201` on resource creation.
`204 No Content`	Success with no body (e.g. a `DELETE`).
`400 Bad Request`	Invalid input — see validation errors below.
`401 Unauthorized`	Missing, malformed, or revoked API key.
`403 Forbidden`	Valid key, but it lacks the required scope, or the workspace trial has expired (`code: trial_expired` — every request is refused, reads included).
`404 Not Found`	The resource doesn’t exist, or isn’t in your workspace.
`405 Method Not Allowed`	The endpoint doesn’t support that HTTP method.
`429 Too Many Requests`	Rate limit exceeded (includes a `Retry-After` header), or a broadcast confirm that doesn’t fit in the monthly quota (`code: monthly_limit_exceeded`).
`500 Internal Server Error`	An unexpected server error — see below.

Validation errors

Field-level validation errors (400 Bad Request) are the one intentional exception to the single-error envelope. They follow Django REST Framework’s field-keyed convention — a map of field name to a list of messages, so you can surface errors next to the right input:

{
  "phone_number": ["This field is required."],
  "template_name": ["No approved template with this name exists in your workspace."]
}

Non-field errors appear under non_field_errors:

{
  "non_field_errors": ["Either `text` or `template_name` must be provided, not both."]
}

When parsing a 400, check for the error key first; if it’s absent, treat the body as a field → messages map.

Server errors

A 500 never leaks internal detail. The full exception (including stack trace) is captured server-side; the client always receives a fixed, parsable body:

{
  "error": "An unexpected error occurred. Please try again or contact support if the problem persists."
}

If you hit a reproducible 500, contact support with the timestamp and endpoint — we can correlate it to the captured exception. A request to an unrouted /api/v1/... path (a typo’d or non-existent endpoint) returns 404 with the same envelope, {"error": "Not found"}.

​The error envelope

​Machine-readable codes

​Status codes

​Validation errors

​Server errors

The error envelope

Machine-readable codes

Status codes

Validation errors

Server errors