Common Errors

The API uses standard HTTP status codes. Errors return a JSON body with status, error, and error_details fields.

Error Response Format

{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Description of what went wrong"
  }
}

Status Codes

400 Bad Request

The request is malformed or contains invalid parameters. Check query parameters, request body, and content types.

{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Invalid value for parameter 'limit'"
  }
}

401 Unauthorized

The access token is missing, malformed, or expired. See Authentication for how to create a new token.

{
  "status": 401,
  "error": "Unauthorized",
  "error_details": {
    "access_token": "The access token expired."
  }
}

403 Forbidden

The token is valid but lacks the required scope for this endpoint. Check that the token has public-api:read or public-api:write as needed.

{
  "status": 403,
  "error": "Forbidden",
  "error_details": {
    "access_token": "The request requires higher privileges"
  }
}

404 Not Found

The resource does not exist, or the token's project does not have access to it.

{
  "status": 404,
  "error": "Not Found",
  "error_details": {
    "url": "/api/2026-01/documents/999999/latestPublication"
  }
}

409 Conflict

A version conflict occurred. This typically happens with document commands when the document was modified by another request between your read and write. Retry the request with the current version.

{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "message": "Version mismatch"
  }
}

410 Gone

The requested API version has been removed. This happens when you call an API version that has reached end of life. Update the version in your request URL to a supported version.

{
  "status": 410,
  "error": "Gone",
  "error_details": {
    "message": "API version '2024-01' is no longer available. Please upgrade to a supported version."
  }
}

429 Too Many Requests

Rate limiting is active. Wait before retrying. The Retry-After header indicates how many seconds to wait.

{
  "status": 429,
  "error": "Too Many Requests",
  "error_details": {
    "message": "Rate limit exceeded"
  }
}

Next Steps

• Authentication — Set up your access token
• Introduction — Overview of the Public API