Clausum uses conventional HTTP status codes. 2xx indicates success, 4xx indicates a problem with your request, and 5xx indicates a problem on Clausum’s side.
Status codes
| Status | Meaning |
|---|
200 | Success |
201 | Resource created |
400 | Validation error — missing or invalid fields |
401 | Unauthorized — missing, invalid, disabled, revoked, or expired credential |
403 | Forbidden — authenticated but missing the required permission or role |
404 | Not found |
409 | Conflict — resource already exists or already in the target state |
429 | Too many requests — rate limit exceeded |
500 | Internal server error |
503 | Service unavailable |
Error shape
Most management endpoints return a structured error object:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "list_type and value are required",
"details": {}
}
}
/api/v1/assess, /api/v1/report-fraud, /api/v1/merchant/*) always return the structured object above, including codes such as SECRET_KEY_REQUIRED, PUBLIC_KEY_NOT_ALLOWED, and RATE_LIMIT_EXCEEDED.
Use error.message for user-facing copy and error.code for branching logic. On 429, honor X-RateLimit-Reset and back off.
Common codes
| Code | Typical cause |
|---|
UNAUTHORIZED | No or bad credential |
FORBIDDEN | Key/role lacks permission |
VALIDATION_ERROR | Missing or malformed body / params |
INVALID_TYPE | Unsupported list_type |
INVALID_SEVERITY | Unsupported severity |
DUPLICATE | Entry already exists |
NOT_FOUND | Resource does not exist |
RATE_LIMITED | Too many requests |
INTERNAL_ERROR | Unexpected server error |
Handling errors
const res = await fetch(url, options)
if (!res.ok) {
const body = await res.json().catch(() => ({}))
const message = typeof body.error === "string" ? body.error : body.error?.message
const code = typeof body.error === "object" ? body.error?.code : undefined
switch (res.status) {
case 401: throw new AuthError(message)
case 403: throw new PermissionError(message)
case 429: return retryWithBackoff()
default: throw new ClausumError(code, message)
}
}
For 5xx and 429 responses, retry with exponential backoff. For 4xx responses other than 429, fix the request — retrying won’t help.
