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.

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 (writes become read-only).
`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.
`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 a completely unrouted /api/v1/... path (a typo’d or non-existent endpoint) returns Django’s HTML 404 page rather than the JSON envelope above. Always confirm your path matches an endpoint in the API Reference — every routed endpoint returns JSON, but an unknown path does not.

​The error envelope

​Status codes

​Validation errors

​Server errors

The error envelope

Status codes

Validation errors

Server errors