DocsError codes

Error codes

The FindIP API uses standard HTTP status codes and returns JSON error responses with detail about what went wrong.

Error response shape

Every error response follows this structure:

JSON

{
"detail": "Human-readable error message"
}

HTTP status codes

Success

Code	Status	Description
`200`	OK	The request succeeded.
`300`	Multiple Choices	The document ID matched multiple patents. (See the document detail API.)

Client errors

Code	Status	Description
`400`	Bad Request	Malformed request. Missing required fields (e.g. `query`) or invalid parameter type/value.
`401`	Unauthorized	Missing or invalid API key. Check the Authorization header.
`403`	Forbidden	API key is valid but lacks permission for this operation.
`404`	Not Found	The requested resource doesn't exist (e.g. unknown document ID).
`429`	Too Many Requests	Monthly search quota exceeded or 60 requests-per-minute rate limit hit. Upgrade your plan or wait for the next billing cycle.

Server errors

Code	Status	Description
`500`	Internal Server Error	An unexpected server-side error occurred. Retry after a short delay.
`503`	Service Unavailable	The server is temporarily unavailable (maintenance or overload).

Common error scenarios

Missing or invalid API key

401 Unauthorized

{
"detail": "Invalid API key"
}

Make sure your request includes Authorization: Bearer psk_live_xxx.

Monthly search quota exceeded

429 Too Many Requests

{
"detail": "Monthly limit exceeded"
}

You've hit your monthly search quota. The quota auto-resets each billing cycle. Detail / drawings / document fetches are not counted. Check your status on the usage dashboard.

Missing required field

400 Bad Request

{
"detail": "Field 'query' is required"
}

Document not found

404 Not Found

{
"detail": "Document not found"
}

Check the publication_id format. You must use the full ID including country code (e.g. US12261291B2, not 12261291).

Error handling best practices

Always inspect the HTTP status code before parsing the response body.
For 429 and 500 errors, retry with exponential backoff.
Log the full error response for debugging — the detail field carries the key information.
When you receive 300 Multiple Choices, present the candidate list to the user for selection.
Set sensible request timeouts (30 s for search, 10 s for other endpoints recommended).

Authentication Next: Developer Guide