Error handling
Understand Adloom API error responses, status codes, and how to handle errors gracefully.
Overview
When an error occurs, the Adloom API returns an appropriate HTTP status code and a JSON error response. All error responses follow a consistent format that makes it easy to handle errors programmatically.
Error response format
All error responses are returned as JSON in the following format:
{
"error": "A human-readable error message",
"code": "ERROR_CODE",
"detail": "Additional context or suggestions (optional)"
}HTTP status codes
The API uses standard HTTP status codes to indicate the success or failure of a request.
Success
The request was successful and the response contains the requested data.
The request is malformed or missing required parameters. Common causes:
- - Missing or invalid file parameter
- - Invalid multipart/form-data encoding
- - Invalid target_platform value
- - File larger than maximum size
Authentication failed. Common causes:
- - Missing or invalid API key
- - Malformed Authorization header
- - API key has been revoked
The request is not allowed for this API key. Common causes:
- - API plan doesn't support the /fix endpoint (API Scan plan only)
- - API plan doesn't support this operation
- - Invalid target_platform for API Platform keys
The requested endpoint does not exist. Check that your URL and endpoint path are correct.
The ZIP file cannot be processed. Common causes:
- - No index.html found in the ZIP
- - Corrupted or invalid ZIP file
- - Unsupported file format inside ZIP
Your API key's monthly quota has been exceeded. The request cannot be processed until your quota resets.
Response includes headers showing your quota status:X-Adloom-Quota-Remaining,X-Adloom-Quota-Reset.
An unexpected error occurred on the server. Retry your request after a short delay. If the problem persists, contact support.
Error examples
Unauthorized: Missing API key
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": "Missing or invalid API key",
"code": "UNAUTHORIZED",
"detail": "Provide an API key via X-API-Key header or Authorization header"
}Forbidden: Plan doesn't support operation
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "This operation is not available with your current plan",
"code": "PLAN_NOT_SUPPORTED",
"detail": "Upgrade to API Fix plan or higher to use the /fix endpoint"
}Unprocessable: No index.html in ZIP
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": "Unable to process creative file",
"code": "INVALID_CREATIVE",
"detail": "No index.html found in ZIP. Ensure your creative has an HTML entry point at the root"
}Quota exceeded
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-Adloom-Quota-Limit: 1000
X-Adloom-Quota-Used: 1000
X-Adloom-Quota-Remaining: 0
X-Adloom-Quota-Reset: 2026-04-21T14:30:00Z
{
"error": "Monthly quota exceeded",
"code": "QUOTA_EXCEEDED",
"detail": "Your quota will reset on 2026-04-21T14:30:00Z. Upgrade your plan for additional quota"
}Quota and rate limiting
Monthly quotas
Each API key has a monthly quota that resets every 30 days from the key's creation date. The quota includes all operations (scans and fixes) based on your plan.
API Scan: 500 scans per month
API Fix: 500 scans and fixes per month
API Platform: 1,000 scans and fixes per month
API Business: 5,000 scans and fixes per month
API Enterprise: Unlimited
Quota reset
Your quota resets on a 30-day billing cycle starting from your API key's creation date. The exact reset date and time is available in the X-Adloom-Quota-Reset response header as an ISO 8601 timestamp.
Quota response headers
Every API response includes quota information in response headers:
X-Adloom-Quota-Limit: 1000 X-Adloom-Quota-Used: 250 X-Adloom-Quota-Remaining: 750 X-Adloom-Quota-Reset: 2026-04-21T14:30:00Z
- - Quota-Limit: your total monthly quota
- - Quota-Used: operations used so far this month
- - Quota-Remaining: operations available before quota is exceeded
- - Quota-Reset: date and time your quota resets
Error handling best practices
Check response headers
Always check the X-Adloom-Quota-Remaining header to monitor your usage and avoid quota exhaustion.
Implement exponential backoff
For 500 errors and transient failures, implement exponential backoff with jitter before retrying.
Handle 429 gracefully
When you receive a 429 error, check the X-Adloom-Quota-Reset header to inform users when service will resume. Consider queuing requests.
Validate input before uploading
Validate ZIP file structure and size locally before uploading to avoid 400 and 422 errors.
Log errors for debugging
Log the full error response including headers for debugging and support purposes.
Need help?
If you encounter persistent errors or need assistance: