Error Handling

The Rekord API uses standard HTTP status codes and returns structured error responses in a consistent format.

Error response format

All error responses follow this structure:

{
  "error": {
    "status": 422,
    "code": "unprocessable_entity",
    "message": "Field 'annualIncome' does not accept operator 'contains'",
    "details": [
      {
        "field": "annualIncome",
        "issue": "Operator 'contains' is not compatible with field type 'currency'"
      }
    ]
  }
}

Field	Description
status	HTTP status code (matches the response status)
code	Machine-readable error code
message	Human-readable description of the error
details	Optional array of field-level or item-level error details

Common status codes

Client errors (4xx)

Status	Code	When it occurs
400	bad_request	Malformed JSON, missing required fields, invalid parameter format
401	unauthorized	Missing or invalid API token
403	forbidden	Token lacks required scope, or accessing an internal endpoint
404	not_found	Resource does not exist or has been deleted
409	conflict	Precondition not met for the operation — e.g., deleting a model that is not archived, or deleting a model that still has active records
412	precondition_failed	If-Match ETag does not match the current version — the resource was modified since you last read it
422	unprocessable_entity	Semantically invalid request — e.g., writing to a computed field, invalid JSON Logic expression, incompatible filter operator for field type
429	too_many_requests	Rate limit exceeded. Check the Retry-After header.

Server errors (5xx)

Status	Code	When it occurs
500	internal_error	Unexpected server error
503	service_unavailable	The service is temporarily unavailable — retry after a brief delay

Handling errors in practice

Retry strategy

Retryable errors: 429, 500, 503. Use exponential backoff with jitter. For 429, respect the Retry-After header.

Non-retryable errors: 400, 401, 403, 404, 409, 412, 422. Fix the request before retrying.

Conflict resolution (409)

A 409 Conflict indicates a precondition on the operation was not met. Common cases:

• Deleting a model that is not archived: Transition the model to archived first, then delete.

• Deleting a model with active records: Delete or archive all records first.

• Deleting a context that is not archived: Transition the context to archived first.

The error message describes which precondition failed.

Concurrency conflicts (412)

A 412 Precondition Failed means the resource was modified between your read and write. See Versioning & Concurrency for the recommended retry pattern.

Validation errors (422)

A 422 Unprocessable Entity includes details about what failed validation:

{
  "error": {
    "status": 422,
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": [
      {
        "field": "totalExposure",
        "issue": "Cannot write to computed field"
      }
    ]
  }
}