Errors

The API uses standard HTTP status codes and returns errors as problem documents (RFC 9457) with the content type application/problem+json.

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" }
]
}
  • code is stable and machine-readable: branch on it, not on detail.
  • detail is a human-readable explanation for logs and developers.
  • errors lists per-field problems when a request body fails validation.

Status codes

StatusMeaningWhat to do
200, 201, 204SuccessNothing
400The 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
401Missing, unknown, revoked or expired API key (INVALID_API_KEY)Check the X-API-Key header
403The key lacks the required scope (forbidden)Use a key with the scope the operation lists
404The resource doesn't exist in your organisation, or there is no such endpoint (not_found)Check the ID, key or path
405The endpoint doesn't accept this HTTP method (method_not_allowed)Check the method in the API reference
409Conflict 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
429Rate limit exceeded (RATE_LIMITED)Back off and retry; see Rate limits
429Your email provider asked to slow down (send_rate_limited); nothing was sentSend 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
5xxSomething went wrong on our sideRetry with backoff; contact us if it persists

Retrying safely

  • GET, PUT …:upsert and DELETE are safe to retry.
  • POST creates something new each time. For syncs, prefer upserts with your own externalId so a retry after a timeout can never create a duplicate.
  • Idempotency-Key makes any POST, PUT or PATCH safe to retry. Send a unique value per operation (a UUID, or order-10442-confirmation); if the same key comes again within 24 hours you get the first answer replayed (with the header Idempotent-Replayed: true) instead of the work being done twice. A retried transactional email is sent once.
cURL
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 eventId of your own (see Events): the same eventId twice is one event.