Skip to content

Error model

The RFC 9457 error body, error codes and which ones can be retried.

Developer documentation

Every error response is in RFC 9457 format with the application/problem+json content type. Your client should branch on the code field, not on the title, detail or message text: texts can change, codes do not. The texts are in Turkish.

{
  "type": "urn:biik:api:v1:problem:validation_failed",
  "title": "Girdi doğrulanamadı",
  "status": 400,
  "code": "validation_failed",
  "request_id": "5b0d3c9e-2f4a-4e61-9a7b-8c1d2e3f4a5b",
  "errors": [
    { "field": "body.nickname", "code": "unrecognized_keys", "message": "Tanınmayan alan" }
  ]
}

Fields

  • type: the stable URN of the error type, urn:biik:api:v1:problem:<code>.
  • title: a short title for humans.
  • status: the HTTP status code.
  • code: the error code for machines.
  • request_id: the ID of the request. Give this value in a support request.
  • detail: human-readable detail, when present.
  • errors: only in a validation_failed response, field-level errors (field, code, message).

Error codes

codeHTTPDescription
bad_request400Invalid request
validation_failed400The input could not be validated
key_in_query400The key cannot be sent in the query string
cookie_with_key400The key cannot be sent together with a cookie
idempotency_key_required400The Idempotency-Key header is required
idempotency_key_invalid400The Idempotency-Key header is invalid
cursor_invalid400The cursor is invalid or does not belong to this query
unauthorized401Authentication failed
insufficient_scope403The scope of the key does not cover this operation
forbidden403The role of the key does not allow this operation
module_disabled403The module is turned off in this account
trial_ended403The trial has ended, the account is read-only
key_suspended403The key is suspended: its role or binding is invalid
not_found404Record not found
method_not_allowed405Method not supported
idempotency_in_progress409A request with the same Idempotency-Key is still in progress
conflict409The request conflicts with the current state of the record
payload_too_large413The body is too large
unsupported_media_type415Content type not supported
idempotency_key_reused422The Idempotency-Key was used with a different request
rate_limited429Rate limit exceeded
internal_error500Unexpected error
timeout503The request exceeded the time limit

A new error code can be added; the status and meaning of an existing code do not change. Handle a code you do not recognise by its HTTP status.

When to retry

  • 429 rate_limited: wait for the number of seconds in the Retry-After header and repeat (Rate limits).
  • 503 timeout: the request exceeded the time limit and was rolled back. Wait for Retry-After and repeat; for a list request a narrower filter or a smaller page size helps.
  • 409 conflict: the request collided with a concurrent write. If there is a Retry-After header, wait and repeat; otherwise read the current state of the record (for example the work email is in use by another active employee).
  • 409 idempotency_in_progress: the request sent with the same Idempotency-Key is still running. Wait a little and repeat with the same key.
  • 500 internal_error: repeating a POST request with the same Idempotency-Key is safe.
  • The remaining 4xx errors are about the request itself; repeating it unchanged gives the same response.