Errors and limits

The error body and every status (401, 402, 422, 429, 502, 503), what each means and what to do. Limits per call and per key, how usage is counted, the OpenAPI schema and the DB-IP credit.

The error body#

A call that fails gets an HTTP error status and this body:

{
  "error": {
    "code": 401,
    "message": "That API key isn't valid. Make one in Cerberius Agents, Organisation › API."
  }
}

code is the same as the HTTP status.
message says what went wrong, in plain words. Log it, so you can see why a call failed.

A failed call is never counted in your usage.

Every status#

Status	What it means, and what to do
`200`	The check ran. The answer is in `data`. What to do: Read each result. A result can still say a lookup found nothing.
`401`	No key, a key that isn't valid or was removed, or a signed call that doesn't hold. What to do: Check the key. For a signed key, check the clock and the signature: see the common mistakes. Don't retry unchanged.
`402`	Your organisation isn't on a paid plan, or its account is locked because a bill wasn't paid. What to do: An owner or admin chooses a plan, or pays the bill, under Your account › Plan & billing. Calls work again once the plan or payment has gone through.
`422`	The body isn't right. What to do: Fix the body, using the message. Don't retry unchanged.
`429`	More than about 10 calls a second with this key. What to do: Wait as many seconds as the `Retry-After` header says (1), then try again.
`502`	The lookup didn't finish. What to do: Try again after a few seconds.
`503`	The API isn't available right now. What to do: Try again later. Your keys keep working once it's back.

The messages#

Status	Message
`401`	Send your API key in the X-API-Key header.
`401`	That API key isn't valid. Make one in Cerberius Agents, Organisation › API.
`401`	This key needs every call signed: send X-Timestamp (seconds since 1970) and X-Signature (hex HMAC-SHA256 of the timestamp followed by the key, with your signing secret).
`401`	X-Timestamp must be the time in seconds since 1970.
`401`	X-Timestamp is more than 5 minutes away from now. Check your clock.
`401`	X-Signature doesn't match. Sign the timestamp followed by the key.
`402`	The API comes free with every paid plan. An owner or admin can choose one under Your account › Plan & billing.
`402`	Your organisation's billing account is locked because a bill wasn't paid. An owner or admin can pay it under Your account › Plan & billing.
`422`	The body isn't valid JSON of the right shape. See /api/schema.
`422`	Each item must be one of the IP addresses, as text.
`422`	Each item must be one of the email addresses, as text.
`422`	Send `{"data": {"prompt": "..."}}` with the text to check.
`422`	Each item must be a valid IP address. (followed by the lookup's own reason in brackets)
`422`	Each item must be an email address. (followed by the lookup's own reason in brackets)
`429`	Too many calls: at most 10 a second per key.
`502`	The lookup didn't finish. Please try again.
`502`	The lookup gave an answer we couldn't read.
`503`	The API isn't available right now. Please try again later.

What causes a 422#

The body isn't JSON, or the Content-Type: application/json header is missing.
data is missing, or has the wrong shape: a list for IP lookup and email check, an object with prompt for prompt check.
No items, or more than 100.
An item that isn't text, is empty, or is longer than 320 characters.
A prompt that's empty, only spaces, or longer than 4,000 characters.
An item that isn't a valid IP address (IP lookup) or doesn't look like an email address (email check). One such item refuses the whole call, and nothing is counted: remove it and send the rest again.

Other statuses#

A wrong path gets 404, and a GET to a check gets 405. These two have a different body, such as {"detail": "Not Found"}. Check the address and use POST.

Limits#

Limit
Items per call	1 to 100 IP addresses or email addresses, or one prompt.
Item length	An address up to 320 characters. A prompt up to 4,000 characters.
Speed	About 10 calls a second per key. A short burst of up to 20 calls is fine. Above that, calls get `429`.
Time	An email check can take several seconds, longer with many addresses. Let a call run for up to 100 seconds.

The speed limit is per key. Each system that calls the API should have its own key, so one busy system doesn't slow the others. To check more than 100 items, split them into calls of up to 100.

Retrying#

Retry 429 after the Retry-After header's seconds.
Retry 502 and 503 after a pause, waiting longer each time, such as 2, 4, then 8 seconds.
Don't retry 401, 402 or 422 unchanged. They fail the same way until you fix the cause.

Usage#

Each IP address, email address or prompt checked counts once, whichever key it came with. A call with 50 addresses counts 50.
Only calls that succeed count. A call that gets an error counts nothing.
Owners and admins see how much your organisation used This month and Last month under Organisation › API. See The API page in the app.

The OpenAPI schema#

The API's OpenAPI description, as JSON, is at:

https://service.cerberius.com/api/schema

It needs no key. Load it into Postman, or a code generator, to make a client for your language. Answers can hold more fields than the schema lists. Every field is in this Help Center: IP lookup, Email check, Prompt check.

Calling from a browser#

The API answers calls from web pages too. But a key in a web page can be read by anyone who opens it, so call the API from your server, and pass on only what your page needs.

Credit for IP data#

IP lookup's location and network data come from DB-IP, under the CC BY 4.0 licence. If you show that data to people, add a credit nearby: "IP data by DB-IP".