Errors

Predictable failures beat clever surprises.

Error responses use one shape and include a request ID. FRDDB does not leak whether an email exists through error differences.

Error response shape

Use request_id when contacting support or correlating with your logs.

Error body

{
  "error": {
    "code": "invalid_request",
    "message": "email is required",
    "request_id": "req_..."
  }
}

Code	Meaning	Typical status
`invalid_request`	Missing or malformed fields.	400
`unauthorized`	Missing, invalid, or revoked API key.	401
`forbidden`	Valid key without the required scope or entitlement.	403
`rate_limited`	Lookup or write rate limit exceeded.	429
`conflict`	Idempotency key reused with a different payload.	409
`internal_error`	Server failure. Retry with backoff.	500

Responses may include X-RateLimit-Limit, X-RateLimit-Remaining, and X-Request-ID.

Pin request behavior with FRDDB-Version: 2026-05-06. Breaking changes get a new dated version.

/reports and /outcomes accept idempotency keys. Safe retries should reuse the same key and body.