Errors
The API returns conventional HTTP status codes plus a structured JSON body so clients can render field-specific errors.
Status codes
| Status | Meaning |
|---|---|
200 |
Success |
201 |
Created (POST) |
204 |
No content (typically DELETE) |
400 |
Validation failed. Body has field-level errors |
401 |
Missing or invalid auth token |
403 |
Authenticated, and you can open the record (or the endpoint), but your role does not allow this action |
404 |
Record does not exist, exists in another tenant, or is in your org but you are not allowed to open it |
409 |
Conflict, e.g. duplicate unique key |
422 |
Semantically invalid (e.g. illegal state transition) |
429 |
Rate limit exceeded |
5xx |
Server error |
Not found versus forbidden
From django-crm 1.11.0 a record in your own org that you are not allowed to open answers 404 on
every method, with the same body as an id that does not exist. That covers the records themselves,
sales goals, and the comments and attachments on tickets, tasks and invoices: a comment or file on a
record you cannot open is the same 404. It used to answer 403 on some endpoints, which told a
caller that the id was real. A 403 now means you can see the record but
may not do what you asked: a member deleting a deal they can read, or editing a goal they can see,
for example, or anyone but an admin calling an admin-only endpoint.
Validation error shape
{
"error": true,
"errors": {
"email": "Enter a valid email address.",
"custom_fields": {
"bant_score": "must be a number",
"industry": "must be one of ['saas', 'manufacturing']"
}
}
}
- Top-level keys are field names.
- For nested objects (
custom_fields), the value is itself a{ key: message }map. - A single field can have a list of messages if multiple validators fire.
Auth error shape
{
"detail": "Authentication credentials were not provided."
}
Or for an expired access token:
{
"detail": "Token expired.",
"code": "token_not_valid"
}
When you see code: token_not_valid, call POST /api/auth/refresh-token/ and retry the original request.
Rate limiting
Requests made with a key are counted per key, per minute: a personal access token, a connected app's key or the org key. BottleCRM's hosted service allows 1,200 a minute for each. Past that, the answer is 429 with a Retry-After header (in seconds):
{
"detail": "Too many requests. Try again later."
}
Signed-in web and phone sessions are not counted. Self-hosted deployments set the ceiling with API_TOKEN_RATE_PER_MINUTE; left unset, there is none. The public endpoints (web form submit, the help center, the calendar feed and the sign-in requests) keep limits of their own, which also answer 429 with Retry-After.