Errors

One error shape, the codes it uses, and which are worth retrying.

Anything that is not a 2xx carries a body of the same shape, so one branch in your code handles every failure:

{
    "error": {
        "code": "invalid_key",
        "message": "That API key does not exist."
    }
}

code is stable and safe to branch on. message is written for a person and may be reworded, so match on the code rather than the sentence.

Status codes

Status	Means
`200`	The request succeeded.
`202`	Accepted and queued. An analysis that is not cached returns this, with a `Location` header naming where the result will appear.
`400`	The request was malformed: a missing field, a URL that is not a URL.
`401`	No key, an unknown key, or a revoked one.
`403`	A valid key on a plan that does not include what you asked for.
`404`	No such endpoint, or no such thing in this workspace.
`405`	Right path, wrong method. The `Allow` header says which are accepted.
`429`	Too many calls, or the monthly allowance is spent.
`500`	Our fault. Worth reporting with the time it happened.

Error codes

Code	Status	What to do
`missing_key`	401	Send the `Authorization` header.
`invalid_key`	401	Check the key. Guessing does not work: unknown keys are refused identically to malformed ones.
`revoked_key`	401	Somebody revoked it. Create a new one.
`plan_excluded`	403	The plan does not include the API, or not this part of it. Upgrade or stop calling it.
`rate_limited`	429	Wait the `retry_after` seconds and try again.
`quota_exceeded`	429	The monthly allowance is spent. Do not retry in a loop: it will not succeed until the period rolls over.
`invalid_request`	400	Read `message`; it names the field.
`not_found`	404	The path or the resource does not exist in this workspace.

When you run out

Two different limits return 429, and the code tells them apart. rate_limited means too many calls in the last minute and clears by itself; quota_exceeded means the monthly allowance is spent and clears when the period rolls over, or when the plan changes.

{
    "error": {
        "code": "rate_limited",
        "message": "That key has made 60 calls in the last minute.",
        "detail": {
            "limit": 60,
            "retry_after": 60
        }
    }
}

Retry 429 and 500 with a backoff. Do not retry 400, 401 or 403: nothing about them changes by asking again, and a tight retry loop on a bad key just burns your rate limit.

PreviousAuthentication NextReports