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.

Client errors

Code	Status	Description
`400`	Bad Request	Malformed request (e.g. invalid date format, malformed IPC code, or unknown `applicant_match`).
`401`	Unauthorized	Missing or invalid API key. Check the `X-API-Key` header.
`403`	Forbidden	The API key is deactivated.
`422`	Unprocessable Entity	Request validation failed (missing/invalid field type or value).
`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 (including embedding failures). Retry after a short delay.
`503`	Service Unavailable	The server is temporarily unavailable (maintenance, overload, or auth service down).

Common error scenarios

Missing or invalid API key

401 Unauthorized

{
"detail": "Missing X-API-Key header"
}

401 Unauthorized

{
"detail": "Invalid API key"
}

Make sure your request includes the X-API-Key: psk_live_... header.

Deactivated API key

403 Forbidden

{
"detail": "API key is deactivated"
}

The key exists but has been deactivated. Contact us to request a new key.

Monthly search quota exceeded

429 Too Many Requests

{
"detail": "Daily limit exceeded (30/30). Upgrade your plan at https://findip.ai/pricing"
}

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

Request validation error

422 Unprocessable Entity

{
"detail": "query field required"
}

A required field is missing or has the wrong type/value. Check the request schema in the Search API.

Invalid parameter

400 Bad Request

{
"detail": "invalid date: '2024/01/01' (expected YYYY-MM-DD)"
}

Per-item not_found in document details

POST /api/v1/patents/details returns 200 OK even when some IDs cannot be resolved. Each unresolved ID appears in the patents array as {"patent_id": "...", "error": "not_found"} rather than a top-level error. Inspect each entry individually:

200 OK (partial)

{
"patents": [
  { "patent_id": "KR1020230012345A", "metadata": { ... }, "content": "..." },
  { "patent_id": "US99999999B2", "error": "not_found" }
]
}

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.
For POST /api/v1/patents/details, check each item for error: "not_found" even on a 200 response.
Set sensible request timeouts (30 s for search, 10 s for other endpoints recommended).

Authentication Next: Developer Guide