Docs / Errors

Errors

Last updated 2026-11-13

Errors are JSON with a stable code.

Error shape

{
  "error": {
    "code": "not_found",
    "message": "We do not have that recall."
  }
}

Status	Code	Meaning
400	`bad_request`	The request was not shaped right (a bad path value or body). The message says how to fix it.
400	`bad_barcode`	The barcode number is not valid: it must be 8, 12, 13 or 14 digits with a correct check digit.
400	`bad_vin`	The VIN is not 17 valid characters.
401	`missing_key`	No API key was sent. Use the Authorization header.
401	`invalid_key`	The key is not valid.
401	`revoked_key`	The key was revoked. Write to support@recalldb.app.
403	`suspended_key`	The key is suspended for usage that looked like bulk collection. Write to support@recalldb.app with your key id.
403	`plan_limit`	A free key can have 1 watchlist and 1 webhook. Delete the existing one first; more is a planned Pro feature.
404	`not_found`	We do not have that record.
429	`rate_limited`	More than 10 requests in a minute (3 if the key was throttled). Wait for Retry-After.
429	`quota_exceeded`	The key used its 1,000 free requests for the month. It resets on the 1st (UTC).
503	`unavailable`	The data service could not answer. Try again.

Errors never include stack traces, internal paths or your key.