Errors

Every error response returned by the Content Island REST API follows a single, machine-readable contract. The HTTP status code and the error.code field always agree, so you can branch on whichever is more convenient for your client.

Response body

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Content \"abc123\" not found",
    "requestId": "0c3b1c64-3d4f-4f1f-9f4e-3f2c8b9a1e2d"
  }
}

• code — one of the codes listed below. Stable identifier, safe to switch on.
• message — human-readable description of the failure. May change between versions; do not parse.
• requestId — UUID generated per request. The same value is written to the server logs, so it can be quoted to support to pinpoint a specific failure.
• details — optional, code-specific extra information. Present today on VALIDATION_ERROR (see below).

Codes

Code	HTTP	When you might see it
VALIDATION_ERROR	400	Query params or request body failed validation. details.fields lists what.
UNAUTHORIZED	401	Missing, malformed, or expired access token.
FORBIDDEN	403	The token is valid but not allowed to perform this operation.
NOT_FOUND	404	The requested resource does not exist (or is not visible to this token).
CONFLICT	409	The request conflicts with current state (e.g. duplicate unique field).
INTERNAL_ERROR	500	Unexpected server-side failure. The response never includes stacks or internals — those are recorded server-side under requestId.

Validation errors

When the request fails validation, the response carries a details.fields array describing each failure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed. Please check the input values.",
    "requestId": "0c3b1c64-3d4f-4f1f-9f4e-3f2c8b9a1e2d",
    "details": {
      "fields": [
        { "field": "title", "message": "Required" },
        { "field": "slug", "message": "Must be unique" }
      ]
    }
  }
}

The shape of each entry is:

interface ValidationFieldError {
  field: string;   // dotted path or field name
  message: string; // human-readable, may change between versions
}

details is omitted for errors that do not have additional context (e.g. UNAUTHORIZED, NOT_FOUND).

Correlating with support

If you need to report a failure, include the requestId value from the response — it lets us locate the exact request in our logs.

Tip

Using the JavaScript/TypeScript client? Errors thrown by the client expose requestId, code, status, message and details directly on a typed ApiClientError. See Handling errors for the recommended pattern.

Status guarantees

• The HTTP status always matches the code in the body (e.g. code: "NOT_FOUND" is always served as 404).
• Internal failures (500) never expose stack traces, internal paths, or third-party error messages. They are logged server-side, keyed by requestId.
• The body always parses as JSON when Content-Type is application/json. Other responses (gateway errors from infrastructure in front of the API, e.g. an nginx 502 HTML page) may not follow this contract — the client library handles that case gracefully (see fallback).