Errors & rate limits

Every CRM Solid Public API response is JSON. Successful calls return a 2xx status with the resource payload; failed calls return a 4xx or 5xx status with a standard error envelope.

HTTP status codes

Code	Meaning	When it happens
200	OK	The request succeeded and the response body contains the resource.
201	Created	A new resource was created (e.g. POST /v1/contacts, POST /v1/deals, POST /v1/tasks).
202	Accepted	A Telegram message job was accepted and queued for background delivery (POST /v1/telegram/messages).
400	Bad Request	The request body or query parameters failed validation (e.g. none of name, username, or phone supplied; text over 4000 characters; creating a deal already won/lost).
401	Unauthorized	The Authorization: Bearer token is missing or invalid.
403	Forbidden	The API key is valid but lacks the scope required by the operation (e.g. contacts:write).
404	Not Found	The resource does not exist or is not owned by the calling workspace.
429	Too Many Requests	The per-key rate limit was exceeded. See Rate limits.
5xx	Server Error	An unexpected server-side error (internal_error). Safe to retry with backoff.

Error response shape

All error responses share the same envelope (components/schemas/Error):

• error — machine-readable code, one of bad_request, not_found, conflict, unauthorized, forbidden, rate_limited, internal_error.
• message — human-readable explanation.
• details — optional structured context (e.g. field-level validation errors); null when not present.

{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}

A validation failure looks like:

{
  "error": "bad_request",
  "message": "at least one of name, username, phone is required"
}

Rate limits

Rate limits are applied per API key. Every response includes the following headers so you can track your remaining budget:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute for this key.
X-RateLimit-Remaining	Requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp (seconds) when the rate-limit window resets.

When a key exceeds its limit, the API returns 429 with the rate_limited error code:

{
  "error": "rate_limited",
  "message": "rate limit exceeded"
}

Tip

Handle 429 by backing off until the time given in X-RateLimit-Reset. Read the Unix-seconds value from that header, wait until it has passed, then retry. Proactively watch X-RateLimit-Remaining and slow down before you hit zero to avoid being throttled at all.

See also

• Authentication — how to obtain and send your API key.
• API reference — full endpoint, parameter, and schema details.