Errors and Limits
How the CRM API reports errors, and the limits that apply to your requests.
Error format
When a CRM endpoint fails, the reply has an HTTP error status and this body:
Error · json
{
"status": "error",
"message": "Object with name 'vehicles' already exists",
"category": "CONFLICT",
"correlationId": "3f2b8c1e-7a4d-4e9b-b6f0-1c2d3e4f5a6b"
}| Field | Description |
|---|---|
| status | Always "error". |
| message | What went wrong, in plain words. |
| category | The kind of error (see Categories). |
| correlationId | A unique id for this error. Send it to support when you ask for help. |
| errors | Only for validation errors: one entry per invalid field. |
Categories
| Category | HTTP status | Meaning |
|---|---|---|
| VALIDATION_ERROR | 400, 422 | The request body or a value is not valid. |
| INVALID_AUTHENTICATION | 401 | The access token is missing or invalid. |
| MISSING_SCOPES | 403 | You are not allowed to do this in this organization. |
| OBJECT_NOT_FOUND | 404 | The object type, record, property or schema does not exist. |
| CONFLICT | 409 | Something with the same name already exists, or the item is still in use. |
| RATE_LIMITS | 429 | Too many requests. Wait and try again. |
| INTERNAL_ERROR | 500 and others | Something went wrong on our side. |
Note
The token and organization checks, and the rate limit, run before the CRM API. Their replies are short (for example
{ "error": "Unauthenticated" }); see Authentication. Always use the HTTP status first.Validation errors
A validation error lists each invalid field in errors, with the field name in context.propertyName:
Validation Error (400) · json
{
"status": "error",
"message": "Validation failed",
"category": "VALIDATION_ERROR",
"correlationId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"errors": [
{
"message": "The label field is required.",
"context": {
"propertyName": [
"label"
]
}
},
{
"message": "The selected type is invalid.",
"context": {
"propertyName": [
"type"
]
}
}
]
}Rate limits
- Each user can make up to 60 requests per minute.
- Above that, requests get 429 Too Many Requests. The
Retry-Afterheader tells you how many seconds to wait. - Every reply carries
X-RateLimit-LimitandX-RateLimit-Remainingheaders. - Use the batch endpoints to create or read many records in one request.
Too Many Requests (429) · json
{
"message": "Too Many Attempts."
}Values and ids
- Record ids are strings. Keep them as strings in your code.
- Property values are strings (or
null), whatever the property type:"42","true","2026-11-12". Multi-select values are joined with;, for example"red;blue". - Dates in
createdAtandupdatedAtare ISO 8601 in UTC. - Object type ids are strings such as
"0-1"; association type ids are numbers.