Errors
Error response format and HTTP status codes.
When a request fails, the API returns a consistent error envelope:
{
"version": "2.0",
"error": {
"code": "TARGET_ERROR",
"message": "Human-readable explanation.",
"details": { "targetStatus": 404 },
"requestId": "0b9f6c1e-2f4e-4c57-9d59-0d6f3f7f2a10"
}
}Every failure uses this envelope, whatever was wrong with the request. Branch on error.code; message is for humans and may be reworded.
requestId identifies the request in our logs. It is also sent as the X-Request-Id header on every scan and usage response — successful ones too — so you can quote it when reporting a problem.
What the status tells you
The status code says whose problem it is, which decides what to do next:
| Status | Whose problem | Retry? |
|---|---|---|
400, 401 | The request | No — fix the request |
402, 429 | A limit | Yes, after waiting |
422 | The page you asked us to scan | No — the same page will fail the same way |
500, 503, 504 | Ours, or a page too slow to finish | Yes, with backoff |
Error codes
| HTTP | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_JSON | Body is not valid JSON | Fix request body syntax |
| 400 | MISSING_URL | url is absent or empty | Include url in the body |
| 400 | INVALID_URL | url cannot be parsed, is not http(s), or contains credentials | Check the URL |
| 400 | INVALID_REQUEST | A field has the wrong type or is out of range | See error.details.fields |
| 400 | URL_NOT_ALLOWED | The URL is, or leads to, a private or internal address | Scan a publicly reachable URL |
| 401 | UNAUTHORIZED | No API key was sent, or it is invalid or revoked | Check the key — see Authentication |
| 402 | LIMIT_EXCEEDED | The key's monthly scans are used up | Wait for error.details.resetsAt |
| 422 | ACCESS_DENIED | The page refused the scanner (WAF, bot protection, login) | Allowlist the scanner — see below |
| 422 | TARGET_ERROR | The page answered with an error such as 404 or 500 | Check the URL; error.details.targetStatus has the status |
| 422 | UNREACHABLE | The page could not be loaded at all | Verify the domain and that it is online |
| 429 | RATE_LIMITED | Too many requests this minute | Wait for Retry-After seconds |
| 500 | INTERNAL | Unexpected server error | Retry with backoff; report requestId |
| 503 | SCANNER_UNAVAILABLE | The scanner could not start, failed mid-scan, or is busy with other scans (error.details.reason is "busy") | Retry after Retry-After seconds; not counted as a scan |
| 504 | SCAN_TIMEOUT | The page did not finish loading in time | Retry; a very heavy page may never fit |
New codes may be added. Treat an unknown code by its status class.
Validation errors
Field types are checked strictly — a string where a boolean belongs is an error, not a guess. INVALID_REQUEST lists every offending field:
{
"version": "2.0",
"error": {
"code": "INVALID_REQUEST",
"message": "The request body is not valid. See `details.fields`.",
"details": {
"fields": [
{ "field": "forceNew", "message": "Expected boolean, received string" }
]
},
"requestId": "…"
}
}Errors caused by the page
ACCESS_DENIED, TARGET_ERROR and UNREACHABLE all mean the request was fine but the page could not be scanned. error.details.targetStatus carries the HTTP status the page returned, or null if it never answered.
An error page is never measured. A URL that returns 404 gives you TARGET_ERROR, not the footprint of the site's "not found" template.
Handling ACCESS_DENIED
The scanner sends X-CarbonFooter-Scan: 1 on every request. If the site uses bot protection, allowlist requests with this header. The error message repeats this, so it can be passed on to the site owner.
Client example
async function scan(url, { attempts = 3 } = {}) {
for (let attempt = 1; ; attempt++) {
const response = await fetch('https://carbonfooter.nl/api/v2/scans', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CARBONFOOTER_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ url }),
});
const body = await response.json();
if (response.ok) return body;
const { code, message, requestId } = body.error;
const retryable = [429, 500, 503, 504].includes(response.status);
if (!retryable || attempt === attempts) {
throw new Error(`[${code}] ${message} (${requestId})`);
}
const seconds = Number(response.headers.get('Retry-After')) || 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
}
}