Error Codes

API error response format

When an API request fails, the response body contains an error object:

{
  "code": 400,
  "detail": "Human-readable description of the error.",
  "success": false
}

Field	Type	Description
code	integer	HTTP status code
detail	string	Human-readable error message
success	boolean	Always false for errors

Some endpoints return additional fields (e.g. violations for validation errors):

{
  "code": 422,
  "detail": "Validation failed.",
  "success": false,
  "violations": [
    { "propertyPath": "domain", "message": "This value is not a valid hostname." }
  ]
}

HTTP status codes

Status	Meaning	Common causes
400 Bad Request	Malformed request	Missing required field, invalid JSON
401 Unauthorized	Not authenticated	Missing, expired, or invalid JWT token
403 Forbidden	Not authorised	Valid token but insufficient permissions for this resource
404 Not Found	Resource not found	Sitekey ID does not exist, or belongs to another user
409 Conflict	Resource conflict	Duplicate entry (e.g. domain already added)
422 Unprocessable Entity	Validation error	Field value did not pass validation rules
500 Internal Server Error	Server error	Unexpected server-side failure

EU CAPTCHA verification error codes

These codes may appear in the error-codes array of a failed verification response. For the authoritative list see Server-Side Verification.

Authentication errors

Scenario	HTTP code	code in body
No Authorization header	401	401
Expired JWT token	401	401
Invalid JWT token	401	401

When the frontend receives a code: 401 response, it automatically logs the user out and redirects to the home page. For direct API consumers, re-authenticate via /login to obtain a new token.

Rate limiting

If you exceed the request rate limit, the API returns 429 Too Many Requests. Back off and retry after a short delay. The Retry-After header indicates how many seconds to wait.