Error codes
Every API error response uses the same JSON envelope. Use the code field to handle specific cases.
Response envelope
All errors return the same top-level shape.
{
"error": {
"type": "invalid_request_error",
"code": "VALIDATION_ERROR",
"message": "key is required",
"status": 400,
"doc_url": "https://docs.thewitn.com/docs/errors/validation-error"
}
}Validation errors add a details array with the exact fields that failed. Server errors add a request_id you can share with support.
Error types
| Type | When |
|---|---|
invalid_request_error | The request was malformed or rejected. Fix the request before retrying. |
authentication_error | The Authorization header is missing, malformed, or the token is not recognised. |
api_error | An unexpected server-side failure. Retry with exponential back-off. If it persists, contact support with the request_id. |
Error codes
| Code | Status | Type | Description |
|---|---|---|---|
VALIDATION_ERROR | 400 | invalid_request_error | Body or params failed schema validation. |
TOKEN_INVALID | 401 | authentication_error | Token missing, malformed, or not recognised. |
PAYLOAD_TOO_LARGE | 413 | invalid_request_error | Event body exceeded the 256 KiB limit. |
INTERNAL_ERROR | 500 | api_error | Unexpected server error. |