Errors

The Management API, the Content Delivery API and the Customer API return errors in the same shape. A code always has the same HTTP status on every API, so one error handler works for all of them.

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "Another post already uses this slug.",
    "details": { "slug": "how-we-feed-our-starter" }
  }
}

Successful responses never contain error, and no API wraps success in an ok flag.

HTTP status by code

Every code maps to one status. Codes added later follow the same rules, so you can handle a code you have not seen yet by its status.

Each operation in the API reference lists the codes it can return and what they mean for that operation. The OpenAPI documents carry the same list as x-kanorio-errors.

Validation errors

VALIDATION lists every failing field in details.issues. path uses dots for nesting.

{
  "error": {
    "code": "VALIDATION",
    "message": "Input does not match the capability schema.",
    "details": {
      "issues": [
        { "path": "title", "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Form submissions on the Content Delivery API report invalid answers the same way, with the question id as the path.

Retries

• Retry 429, 502 and 503 with backoff. When the response has a Retry-After header or details.retryAfter, wait at least that many seconds.
• Do not retry other 4xx responses unchanged. Fix the request first.
• 409 CONFLICT on a write means someone changed the resource after you read it. Read it again, merge, and send the write with the new timestamp.
• Make create requests safe to retry with an idempotency key.

Permission errors

403 responses explain what is missing in details, for example the requiredScope the token lacks or reason: "principal_not_allowed" when a service account calls an account-level operation. Show the user what to change instead of retrying.

Request IDs

Content Delivery API and Customer API responses carry an X-Request-Id header. Include it when you contact support about a specific request.

Error codes

The tables below list every code each API can return today, generated from the OpenAPI documents.

Management API codes

Content Delivery API codes

Customer API codes