All error responses follow a consistent envelope:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{ "type": "field_error", "field": "uploadIds", "message": "Required" }
]
},
"correlationId": "uuid-for-support"
}
Error Codes
| Code | HTTP Status | Meaning | Recommended Action |
|---|
VALIDATION_ERROR | 400 | Request body failed schema validation | Fix the request payload per the details array |
UNAUTHORIZED | 401 | Missing or invalid API key | Check Authorization header and key validity |
FORBIDDEN | 403 | API key lacks permission for this resource | Contact Adclear to adjust key scoping |
NOT_FOUND | 404 | Resource does not exist | Verify the resource ID; it may have been deleted |
CONFLICT | 409 | Resource not in expected state (e.g. uploads not ready) | Retry with back-off |
RATE_LIMITED | 429 | Too many requests | Honour the Retry-After header |
INTERNAL_ERROR | 500 | Unexpected server error | Retry once; if persistent, contact support |
Always include the correlationId in support requests. It allows us to trace the full request lifecycle for fast debugging.
