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 avalidation_failedresponse, field-level errors (field,code,message).
Error codes
| code | HTTP | Description |
|---|---|---|
bad_ | 400 | Invalid request |
validation_ | 400 | The input could not be validated |
key_ | 400 | The key cannot be sent in the query string |
cookie_ | 400 | The key cannot be sent together with a cookie |
idempotency_ | 400 | The Idempotency-Key header is required |
idempotency_ | 400 | The Idempotency-Key header is invalid |
cursor_ | 400 | The cursor is invalid or does not belong to this query |
unauthorized | 401 | Authentication failed |
insufficient_ | 403 | The scope of the key does not cover this operation |
forbidden | 403 | The role of the key does not allow this operation |
module_ | 403 | The module is turned off in this account |
trial_ | 403 | The trial has ended, the account is read-only |
key_ | 403 | The key is suspended: its role or binding is invalid |
not_ | 404 | Record not found |
method_ | 405 | Method not supported |
idempotency_ | 409 | A request with the same Idempotency-Key is still in progress |
conflict | 409 | The request conflicts with the current state of the record |
payload_ | 413 | The body is too large |
unsupported_ | 415 | Content type not supported |
idempotency_ | 422 | The Idempotency-Key was used with a different request |
rate_ | 429 | Rate limit exceeded |
internal_ | 500 | Unexpected error |
timeout | 503 | The 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 theRetry-Afterheader and repeat (Rate limits).503 timeout: the request exceeded the time limit and was rolled back. Wait forRetry-Afterand 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 aRetry-Afterheader, 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 sameIdempotency-Keyis still running. Wait a little and repeat with the same key.500 internal_error: repeating aPOSTrequest with the sameIdempotency-Keyis safe.- The remaining
4xxerrors are about the request itself; repeating it unchanged gives the same response.