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.
Rate Limits
| Service | Scope | Limit | Notes |
|---|
| Integration API | All /v1/* endpoints | 60 requests per minute | Per API key |
| File API | POST /v1/uploads (initiation only) | 30 requests per minute | Per API key |
PUT /v1/uploads/{id}) and status checks (GET /v1/uploads/{id}) are not rate-limited.
When rate-limited, the response includes a Retry-After header indicating how many seconds to wait before retrying. See Troubleshooting for more guidance. 
