REST API error codes

API error codes and handling

Certorix REST API returns standard HTTP status codes with JSON error bodies.

Success codes

• 200 OK – Request succeeded.
• 201 Created – Resource created successfully (POST requests).
• 204 No Content – Request succeeded, no body returned (DELETE, some PUT).

Client error codes (4xx)

• 400 Bad Request – Malformed request, missing required field, or validation failed. Check error.details for specifics.
• 401 Unauthorized – Missing or invalid Authorization header.
• 403 Forbidden – Authenticated but not allowed (e.g., Viewer trying to edit).
• 404 Not Found – Resource (tree, fact, session) does not exist.
• 409 Conflict – Resource already exists with same ID, or operation conflicts with current state (e.g., trying to publish an invalid tree).
• 429 Too Many Requests – Rate limit exceeded. Wait and retry after the Retry-After header.

Server error codes (5xx)

• 500 Internal Server Error – Unexpected server error. Retry with exponential backoff.
• 503 Service Unavailable – API is temporarily offline (maintenance). Check status page.

Example error response

{
  "error": "Validation failed",
  "status": 400,
  "details": {
    "field": "metadata.startNodeId",
    "message": "startNodeId does not reference an existing node"
  }
}