Errors

Errors come back with an HTTP status and one JSON shape. error_description is written for people: show it or log it.

Error shape

{
  "error": "invalid_request",
  "error_description": "Add at least one filter (firm, q, fei, center, classification, status, recall_number or a date range)."
}

Status and error codes#

Status and codeWhen, and what to do

400 invalid_request

A parameter is missing or not valid. error_description says which one and how to fix it.

401 unauthorized

No Authorization header. The WWW-Authenticate header points to the OAuth metadata.

401 invalid_token

The API key or access token is unknown, expired or revoked.

403 subscription_required

The account has no active Standard or Premium plan.

404 not_found

No document, firm, investigator, CFR section, endpoint or tool with that id or name.

429 limit_reached

The plan's daily cap or monthly requests are used up. Retry-After says when it resets.

429 rate_limited

More than 600 requests in one minute. Wait a minute (Retry-After: 60).

500 server_error

Something failed on our side. Retry once; if it persists, contact us.

Document text and PDFs#

Document records always carry "full_text": "not_included": the API gives the summary, the data and the opening words of each observation, plus the document's link on FDA Intel. This is a normal reply (status 200), not an error.

MCP errors#

A tool that cannot answer (bad input, nothing found, a limit reached) returns a normal result with isError: true and the message as text, so the assistant can explain it. Protocol problems use JSON-RPC error codes:

-32700

Parse error: the body is not JSON.

-32600

Invalid request: not a JSON-RPC 2.0 message.

-32601

Method not found.

-32602

Unknown tool name.

Retrying#

Retry only 429 (after Retry-After seconds) and 500 (once, after a short wait). Fix the request for every other error.