Public API Errors

Every error the public API answers has the same shape, whichever part of HeaderHawk produced it:

{
  "error": {
    "code": "validation_error",
    "message": "limit must be a whole number from 1 to 200.",
    "requestId": "c39fa2e6-84a8-4857-80b6-c28a3ca663cc"
  }
}

• code says what went wrong. Branch on it.
• message says it for people, and may be reworded at any time. Do not match on it.
• requestId identifies the request. Quote it when you write to us.

Every code

Code	Status	What it means	Retry?
validation_error	400	A parameter is wrong: a value outside its range, a window longer than the operation allows, an unknown parameter, or a cursor sent with different parameters from the page that returned it. The message names it.	No: fix the request
bad_request	400, 413, 415	HeaderHawk could not read the request at all.	No: fix the request
invalid_api_key	401	The key is missing, malformed, unknown, revoked or expired. The answer is the same for all five.	No: use a valid key
plan_upgrade_required	403	Your plan does not include what you asked for: API access itself, or a feature an operation needs. The key works again when the plan does.	No
forbidden	403	The key may not do this, whatever the plan.	No
not_found	404	No such operation, or no such site, issue, page, scan or script in your account. Another account’s id is 404 too.	No
rate_limited	429	Over a rate limit: the key’s, your account’s budget for reported data, or HeaderHawk’s overall limit when the API is busy.	Yes, after Retry-After seconds
rate_limit_unavailable	503	HeaderHawk could not count your account’s budget just then, so it read nothing.	Yes, after Retry-After seconds
upstream_unavailable	503, 504	HeaderHawk could not answer just then: a read took too long, or the API was briefly unavailable.	Yes, after Retry-After seconds
internal_error	500	Something went wrong on our side.	Not usually: quote the requestId to us

A 429 and every 503 carry a Retry-After header. A 503 is never a sign that the request was wrong: send the same request again once it has passed.

The list of codes is open. A code this page does not list may be added inside v1; treat one you do not know by its HTTP status.

Rate limit headers

A request that reaches a rate limit, which is every one with a valid key and valid parameters, carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for whichever budget is nearest to running out. A request refused before that, for a bad key or a bad parameter, carries none and spends nothing. Getting started has the limits themselves and a retry loop.