Skip to Content
CarbonFooterv2.0

Errors

Error response format and HTTP status codes.

When a request fails, the API returns a consistent error envelope:

Error response
{
  "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:

StatusWhose problemRetry?
400, 401The requestNo — fix the request
402, 429A limitYes, after waiting
422The page you asked us to scanNo — the same page will fail the same way
500, 503, 504Ours, or a page too slow to finishYes, with backoff

Error codes

HTTPCodeMeaningWhat to do
400INVALID_JSONBody is not valid JSONFix request body syntax
400MISSING_URLurl is absent or emptyInclude url in the body
400INVALID_URLurl cannot be parsed, is not http(s), or contains credentialsCheck the URL
400INVALID_REQUESTA field has the wrong type or is out of rangeSee error.details.fields
400URL_NOT_ALLOWEDThe URL is, or leads to, a private or internal addressScan a publicly reachable URL
401UNAUTHORIZEDNo API key was sent, or it is invalid or revokedCheck the key — see Authentication
402LIMIT_EXCEEDEDThe key's monthly scans are used upWait for error.details.resetsAt
422ACCESS_DENIEDThe page refused the scanner (WAF, bot protection, login)Allowlist the scanner — see below
422TARGET_ERRORThe page answered with an error such as 404 or 500Check the URL; error.details.targetStatus has the status
422UNREACHABLEThe page could not be loaded at allVerify the domain and that it is online
429RATE_LIMITEDToo many requests this minuteWait for Retry-After seconds
500INTERNALUnexpected server errorRetry with backoff; report requestId
503SCANNER_UNAVAILABLEThe 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
504SCAN_TIMEOUTThe page did not finish loading in timeRetry; 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:

400 INVALID_REQUEST
{
  "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

scan.js
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));
  }
}

On this page