Errors

Format

Errors are JSON with a single detail field. For most errors it is a sentence; for validation errors it is a list of problems.

{ "detail": "monthly quota of 1000 classifications exceeded" }

{
  "detail": [
    { "type": "missing", "loc": ["body", "message"], "msg": "Field required" }
  ]
}

Validation errors never echo your input back.

Status codes

code	meaning	what to do
200	Success.	Use the response.
201	Created (site keys).	Store the returned key; it is shown once.
400	Malformed JSON.	Fix the request.
401	Missing or invalid key. Header WWW-Authenticate: Bearer.	Check the key and the header format. Alert yourself; deliver the message.
402	Monthly quota exhausted.	Deliver the message. Upgrade the plan or wait for the month to roll over. GET /v1/usage shows the numbers.
403	Key revoked, or a site key calling a platform endpoint.	Alert yourself; deliver the message.
404	Unknown id, or an id that belongs to another key.	Nothing to retry.
413	Request body over 32 KB.	Trim the message before sending.
422	Validation error; detail lists the fields.	Fix the payload. Deliver the message.
429	Over the per-minute rate limit. Header Retry-After in seconds.	Back off for Retry-After. Deliver the message.
503	Service cannot classify right now (a deploy in progress).	Retry once after a second; then deliver the message.

The rule for form handlers

Deliver on every failure. A lost enquiry costs more than one spam email. The only exceptions are forms whose submit triggers an expensive action, where failing closed is the safer default.

200            use the label
401 / 403      configuration problem: deliver, alert yourself
402            quota exhausted: deliver, alert yourself
413 / 422      your payload: deliver, fix the request
429            back off per Retry-After, deliver
5xx / timeout  deliver

Rate limits

Limits use a token bucket, so short bursts above the per-minute figure are fine. The defaults are 60 requests per minute per key and 20 per minute per IP for unauthenticated requests. Higher limits are available on request. See Limits and quotas.