Errors
The API uses standard HTTP status codes and returns errors as problem documents (RFC 9457) with the content type application/problem+json.
{"type": "about:blank","title": "Bad Request","status": 400,"detail": "The record has invalid fields.","code": "record_validation_error","errors": [{ "field": "email", "message": "must be a valid email address" },{ "field": "locale", "message": "must be one of: sv, en" }]}
codeis stable and machine-readable: branch on it, not ondetail.detailis a human-readable explanation for logs and developers.errorslists per-field problems when a request body fails validation.
Status codes
| Status | Meaning | What to do |
|---|---|---|
200, 201, 204 | Success | Nothing |
400 | The request is invalid (validation_error, record_validation_error, invalid_filter, malformed_body for a body that isn't valid JSON, invalid_parameter for e.g. an id that isn't a UUID, …) | Fix the request; see errors |
401 | Missing, unknown, revoked or expired API key (INVALID_API_KEY) | Check the X-API-Key header |
403 | The key lacks the required scope (forbidden) | Use a key with the scope the operation lists |
404 | The resource doesn't exist in your organisation, or there is no such endpoint (not_found) | Check the ID, key or path |
405 | The endpoint doesn't accept this HTTP method (method_not_allowed) | Check the method in the API reference |
409 | Conflict with the current state (e.g. invalid_transition, concurrent_update, definition_in_use when deleting a field a segment or automation still uses, tag_in_use) | Re-read the resource; the detail names what to change first |
429 | Rate limit exceeded (RATE_LIMITED) | Back off and retry; see Rate limits |
429 | Your email provider asked to slow down (send_rate_limited); nothing was sent | Send it again shortly. Campaigns and automations do this themselves; set the sending speed (PUT /api/v1/settings/email/speed) to your provider's limit to avoid it |
5xx | Something went wrong on our side | Retry with backoff; contact us if it persists |
Retrying safely
GET,PUT …:upsertandDELETEare safe to retry.POSTcreates something new each time. For syncs, prefer upserts with your ownexternalIdso a retry after a timeout can never create a duplicate.Idempotency-Keymakes anyPOST,PUTorPATCHsafe to retry. Send a unique value per operation (a UUID, ororder-10442-confirmation); if the same key comes again within 24 hours you get the first answer replayed (with the headerIdempotent-Replayed: true) instead of the work being done twice. A retried transactional email is sent once.
curl -X POST https://crm.codefab.dev/api/v1/emails:send -H "X-API-Key: cfk_…" -H "Idempotency-Key: order-10442-confirmation" -H "Content-Type: application/json" -d '{ … }'
The same key for a different request is refused with 422 idempotency_key_reused; a retry while the first is still running gets 409 idempotency_in_progress: wait a moment and retry. Server errors (5xx) are not remembered, so they can be retried with the same key.
- Events take an
eventIdof your own (see Events): the sameeventIdtwice is one event.