Skip to content
Start free Sign in

Handle API errors

Agency plan

Last updated

Available on the Agency plan

This feature is included in the Agency plan and the plans above it. See pricing

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": "..."}
  ]
}
  • code is the stable name of the error. Let your software decide by code, never by title or detail, whose wording can change.
  • type is the address of a page about that code.
  • status repeats the HTTP status.
  • detail says what happened and what to do, for a person to read.
  • request_id is the id of the request, the same as the Request-Id header. Quote it when you contact support.
  • errors has one entry for each parameter that needs changing. It has entries with validation_failed, and with a 409 conflict for a site's domain or external_id that 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.

CodeStatusTitle
bad_request400Bad request
unauthenticated401Unauthenticated
forbidden403Forbidden
insufficient_scope403Insufficient scope
plan_upgrade_required403Plan upgrade required
concurrency_limited429Too many concurrent requests
not_found404Not found
method_not_allowed405Method not allowed
conflict409Conflict
precondition_failed412Precondition failed
payload_too_large413Request body too large
credential_in_query400Credential in the query string
validation_failed400, 422Validation failed
idempotency_key_missing400Idempotency key missing
idempotency_key_reuse422Idempotency key reused
idempotency_in_flight409Request still in progress
site_limit_reached403Site limit reached
site_frozen403Site frozen
scan_in_progress409Scan in progress
queue_full429Scan queue full
report_not_ready409Report not ready
rate_limited429Too many requests
service_unavailable503Service unavailable
internal_error500Internal error

Which errors to retry

  • 429 (rate_limited, concurrency_limited, queue_full): wait the number of seconds in the Retry-After header, then send the request again.
  • 409 idempotency_in_flight: an earlier request with the same Idempotency-Key may still be running. Wait the seconds in Retry-After, then send it again.
  • 409 report_not_ready: the scan report, or its PDF, is not ready yet. Wait the seconds in Retry-After, then ask again.
  • 503 service_unavailable and 500 internal_error: send the request again after a pause. When the answer has a Retry-After header, wait that many seconds, and otherwise wait longer after each failure. After an error the API does not keep an answer for the Idempotency-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 a scan_id has 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 new etag. One case differs: an operation on something that has no etag yet, such as creating a region rule, moving cookies into a category or adding a language's first banner texts, answers 412 for any well-formed If-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.

Was this helpful?

Listed on