Error codes

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

Error response shape

Most error responses follow this structure:

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

The one exception is 422 validation errors, where detail is an array of per-field error objects rather than a string. Check the type before treating detail as a string.

HTTP status codes

Success

Client errors

Server errors

Common error scenarios

Missing or invalid API key

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

{
"detail": "Invalid API key"
}

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

Deactivated API key

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

The key exists but has been deactivated. Contract customers can issue a new key on the API keys page of the dashboard.

Insufficient search credits

Unused search credits do not carry over into the next cycle. They have no cash value and cannot be transferred. An accepted text search uses 1 credit; image (drawing) search, sequence search, and trend analysis use 2; details, drawings, and number lookups use 0. If an LLM performs multiple searches for one response, each accepted search uses credits separately. See the table in Authentication for the full per-operation rate.

The per-minute rate limit counts requests separately from credits, including 0-credit calls. The detail text and optional metadata can vary by backend version, so clients should handle the HTTP 429 status rather than parse the message string. Check your credit balance on the usage dashboard.

Request validation error

{
"detail": [
  {
    "type": "string_type",
    "loc": ["body", "query"],
    "msg": "Input should be a valid string",
    "input": 123
  }
]
}

A field's type or value does not match the schema. loc gives the offending field path and msg the reason. Check the request schema in the Search API.

Sending an undefined field is not an error — the server silently ignores it and returns 200, so a misspelled parameter name shows up as an unfiltered result set, not an error.

Invalid parameter

{
"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:

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

Error handling best practices

1. Always inspect the HTTP status code before parsing the response body.
2. For 429 and 500 errors, retry with exponential backoff.
3. Log the full error response for debugging — the detail field carries the key information.
4. For POST /api/v1/patents/details, check each item for error: "not_found" even on a 200 response.
5. Set sensible request timeouts. Search typically completes in 2–6 s, so allow 30 s for headroom, and 10 s for other endpoints such as document details, drawings and coverage.