API errors

Every error code the API returns, its HTTP status, and what to do about it.

Every error has the same body:

json

{
  "error": {
    "code": "quota_exhausted",
    "message": "This month's takedowns are used up."
  }
}

Branch on code. The message is for people: it can change wording at any time, so don't match on it.

Error codes

Code	HTTP	Meaning	What to do
`invalid_request`	400	A field is missing, has the wrong type, or isn't allowed: an IP address instead of a domain name, an address on a private network, one of your own domains, a well-known platform, a domain that doesn't exist, or a URL with nothing a takedown can be filed against (see Open a case for each message)	Fix the request; the message says what is wrong. Don't retry unchanged
`unauthorized`	401	The key is missing, invalid, revoked or expired. The message is the same in every case	Check the `Authorization: Bearer` header and the key in the console. Don't retry with the same key
`quota_exhausted`	402	This month's takedowns are used up	Report the URL in the console, then add a $199 takedown on its case page; or wait for next month. The API never charges
`plan_required`	403	The organization isn't on the Enterprise plan	Ask an owner to move the organization to Enterprise. The keys work again as soon as it is
`ip_not_allowed`	403	The key has an IP allowlist and the request came from an address that isn't on it	Send the request from an allowed address, or have an owner or admin add the address to the key in the console. Don't retry unchanged
`insufficient_scope`	403	The key doesn't have the scope this endpoint needs: `cases:read` for `GET /cases` and `GET /cases/{id}`, `cases:write` for `POST /cases`	Use a key with that scope, or have an owner or admin add it to the key
`not_found`	404	No such case in your organization, or no such endpoint	Check the ID and the path. Cases of other organizations are never visible
`idempotency_conflict`	409	Either a request with this `Idempotency-Key` is still being processed, or the key was used in the last 24 hours with a different body. The message says which	Still processing: wait a few seconds and retry with the same key. Different body: use a new key, and only for a new request
`payload_too_large`	413	The request body is over 16 KB	Shorten the `note`
`rate_limited`	429	More than 60 requests in a minute with this key. Requests from the same IP address also share a limit, whichever key they use	Wait the number of seconds in `Retry-After` (always 60), then retry
`internal_error`	500	Something went wrong on our side	Retry with backoff. On `POST /cases`, send the same `Idempotency-Key` so a retry can't open a second case

A method a path doesn't take answers 405 with code invalid_request. A request that runs longer than 30 seconds can get 504 Gateway Timeout with no JSON body, so check the status code and Content-Type before parsing a response as JSON.

Retrying

Retry 429 after Retry-After, and 5xx or a network error with exponential backoff (for example 1 s, 2 s, 4 s, up to a minute). A 5xx answer isn't kept under the Idempotency-Key, so a retry with the same key is processed again.
Don't retry other 4xx errors unchanged: the same request gets the same answer. The exception is 409 while the first request is still being processed: retry with the same key after a few seconds.
Always send an Idempotency-Key on POST /cases, so a retry is safe even when you never saw the first response.

Webhooks Examples