When a request fails, the Kukie.io API answers with an HTTP status of 400 or above and a JSON body of one shape. This guide explains the body, lists every error code, and says which errors are worth a retry.
The error body
Errors are sent as application/problem+json:
{
"type": "https://kukie.io/docs/api/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"detail": "Some parameters need changing. Each entry in errors names one and says what to change.",
"code": "validation_failed",
"request_id": "req_...",
"errors": [
{"param": "limit", "code": "invalid", "message": "..."}
]
}
codeis the stable name of the error. Let your software decide bycode, never bytitleordetail, whose wording can change.typeis the address of a page about that code.statusrepeats the HTTP status.detailsays what happened and what to do, for a person to read.request_idis the id of the request, the same as theRequest-Idheader. Quote it when you contact support.errorshas one entry for each parameter that needs changing. It has entries withvalidation_failed, and with a 409conflictfor a site'sdomainorexternal_idthat another site already uses. With other codes it is normally empty.
Some codes add members of their own, such as required_scope with insufficient_scope. The page of each code lists them.
The servers in front of the API can answer before the API does: with 413 for a request body far larger than the API accepts, with a 5xx status of their own, such as 502, when the API cannot be reached, or with a page that blocks the request. Such an answer does not have this body and has no Request-Id header, so decide by its HTTP status alone.
Error codes
These are the codes of this version of the API, in the order the API reference lists them. New codes can be added, so treat a code your software does not know like its status alone.
| Code | Status | Title |
|---|---|---|
bad_request | 400 | Bad request |
unauthenticated | 401 | Unauthenticated |
forbidden | 403 | Forbidden |
insufficient_scope | 403 | Insufficient scope |
plan_upgrade_required | 403 | Plan upgrade required |
concurrency_limited | 429 | Too many concurrent requests |
not_found | 404 | Not found |
method_not_allowed | 405 | Method not allowed |
conflict | 409 | Conflict |
precondition_failed | 412 | Precondition failed |
payload_too_large | 413 | Request body too large |
credential_in_query | 400 | Credential in the query string |
validation_failed | 400, 422 | Validation failed |
idempotency_key_missing | 400 | Idempotency key missing |
idempotency_key_reuse | 422 | Idempotency key reused |
idempotency_in_flight | 409 | Request still in progress |
site_limit_reached | 403 | Site limit reached |
site_frozen | 403 | Site frozen |
scan_in_progress | 409 | Scan in progress |
queue_full | 429 | Scan queue full |
report_not_ready | 409 | Report not ready |
rate_limited | 429 | Too many requests |
service_unavailable | 503 | Service unavailable |
internal_error | 500 | Internal error |
Which errors to retry
- 429 (
rate_limited,concurrency_limited,queue_full): wait the number of seconds in theRetry-Afterheader, then send the request again. - 409
idempotency_in_flight: an earlier request with the sameIdempotency-Keymay still be running. Wait the seconds inRetry-After, then send it again. - 409
report_not_ready: the scan report, or its PDF, is not ready yet. Wait the seconds inRetry-After, then ask again. - 503
service_unavailableand 500internal_error: send the request again after a pause. When the answer has aRetry-Afterheader, wait that many seconds, and otherwise wait longer after each failure. After an error the API does not keep an answer for theIdempotency-Key, so a retry runs the request again. If the first request may have done part of its work, read the resource before you repeat it. A 503 for a scan start that carries ascan_idhas already created that scan. - 503 from the consent statistics or from your API usage: the figures took too long to compute. The same request is likely to fail again, and each try of the consent statistics counts against their limit. Wait the seconds in
Retry-After(60 for the statistics, 60 for the usage), then ask for a shorter window. - 412
precondition_failed: the resource changed since you read it. Read it again, apply your change to what you read, and send it with the newetag. One case differs: an operation on something that has noetagyet, such as creating a region rule, moving cookies into a category or adding a language's first banner texts, answers 412 for any well-formedIf-Match. Send it without that header. - 409
scan_in_progress: a scan of the site is waiting or running. Wait for it to finish, then send the request again. - Every other 4xx: read the answer's
detail. It says what has to change first: the request, the state of the resource, or something in your organisation's account, such as its plan or its number of sites. Sending the same request again does not help until that has changed.
Do not treat a 404 not_found as proof that something was deleted. The API also answers 404 for a site your key does not reach, and it can answer 404 for every path while the API is switched off.
