> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinakelai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The problem details format and every error type the API returns.

Every error is a problem details document ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)), served as `application/problem+json` with `Cache-Control: no-store`.

```json theme={null}
{
  "type": "https://docs.pinakelai.com/errors/query-too-broad",
  "title": "Query too broad",
  "status": 422,
  "detail": "mark_text_phrase matches more than 100,000 records. Narrow the search.",
  "request_id": "req_01M7Q3ZV8X1B5C9D2F6G4H8J3K"
}
```

| Member | Type | Meaning |
| - | - | - |
| `type` | string | A URL identifying the error type. Stable: branch on it. It opens the type's page in these docs. |
| `title` | string | A short summary of the type, for people. Can be reworded. |
| `status` | integer | The HTTP status code. |
| `detail` | string | What went wrong with this request, for people. Can be reworded. |
| `request_id` | string | Equals the `X-Request-Id` header. Quote it to support. |
| `errors` | array | `invalid-request` only: every problem found in the request. |
| `violated_policies` | array of strings | 429 only: the policies that refused the call, `minute`, `month` or `concurrency`. |

New members can be added to problem documents; ignore members you do not know.

## Error types

| Status | Type | Title | Retry |
| - | - | - | - |
| 400 | [`invalid-request`](https://docs.pinakelai.com/errors/invalid-request) | Invalid request | No: fix the request |
| 400 | [`invalid-cursor`](https://docs.pinakelai.com/errors/invalid-cursor) | Invalid cursor | No: start again |
| 400 | [`cursor-mismatch`](https://docs.pinakelai.com/errors/cursor-mismatch) | Cursor does not match the request | No: resend the original filters |
| 401 | [`unauthenticated`](https://docs.pinakelai.com/errors/unauthenticated) | Authentication required | No: fix the credential |
| 401 | [`key-revoked`](https://docs.pinakelai.com/errors/key-revoked) | API key revoked | No: use a current key |
| 403 | [`product-not-enabled`](https://docs.pinakelai.com/errors/product-not-enabled) | Product not enabled for this key | No: ask for the product |
| 404 | [`not-found`](https://docs.pinakelai.com/errors/not-found) | Not found | No: an answer |
| 404 | [`unknown-endpoint`](https://docs.pinakelai.com/errors/unknown-endpoint) | Unknown endpoint | No: fix the path |
| 405 | [`method-not-allowed`](https://docs.pinakelai.com/errors/method-not-allowed) | Method not allowed | No: fix the method |
| 410 | [`removed`](https://docs.pinakelai.com/errors/removed) | Removed | No: move to `/v1` |
| 413 | [`payload-too-large`](https://docs.pinakelai.com/errors/payload-too-large) | Payload too large | No: split the batch |
| 415 | [`unsupported-media-type`](https://docs.pinakelai.com/errors/unsupported-media-type) | Unsupported media type | No: send JSON |
| 422 | [`query-too-broad`](https://docs.pinakelai.com/errors/query-too-broad) | Query too broad | No: narrow the query |
| 422 | [`query-timeout`](https://docs.pinakelai.com/errors/query-timeout) | Query timed out | No: narrow the query |
| 429 | [`rate-limited`](https://docs.pinakelai.com/errors/rate-limited) | Rate limit exceeded | Yes, after `Retry-After` |
| 429 | [`quota-exceeded`](https://docs.pinakelai.com/errors/quota-exceeded) | Monthly quota exceeded | After the quota resets |
| 500 | [`internal-error`](https://docs.pinakelai.com/errors/internal-error) | Internal error | Yes, with backoff |
| 503 | [`unavailable`](https://docs.pinakelai.com/errors/unavailable) | Service unavailable | Yes, after `Retry-After` |
| 503 | [`jurisdiction-unavailable`](https://docs.pinakelai.com/errors/jurisdiction-unavailable) | Jurisdiction unavailable | Yes, after `Retry-After` (at least 900 s) |
| 503 | [`search-index-unavailable`](https://docs.pinakelai.com/errors/search-index-unavailable) | Search index unavailable | Yes, later |

The API never returns 504. New types can be added in v1; treat an unknown type by its status code.

## Validation errors

`invalid-request` lists every problem with the request in `errors`. Each entry has a `code`, a `detail`, and either `parameter` or `pointer`:

```json theme={null}
{
  "type": "https://docs.pinakelai.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request has invalid parameters; see errors.",
  "request_id": "req_01M7Q3ZW9Y2C6D1F3G7H5J9K4M",
  "errors": [
    { "code": "invalid-body", "detail": "Not a valid trademark id.", "pointer": "/ids/2" },
    { "code": "invalid-body", "detail": "At most 25 ids with include=source_record.", "pointer": "/ids" }
  ]
}
```

| `code` | Cause |
| - | - |
| `unknown-parameter` | A parameter that does not exist; the `detail` suggests the closest valid one |
| `reserved-parameter` | `q`, which is reserved; use `mark_text_phrase` |
| `missing-filter` | A search with no filter |
| `invalid-parameter` | A value that is malformed, out of range, or not allowed in this combination |
| `query-too-long` | A cursor longer than 6,000 characters, or a query string longer than 32 KB |
| `invalid-body` | A batch body that is not valid JSON, has unknown members, or holds bad or too many ids |
| `not-yet-available` | A parameter reserved for a later version, such as `goods_services_phrase` |

`parameter` names a query parameter. `pointer` is a [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901) into the batch request body. New codes can be added.

## Headers on errors

| Header | On |
| - | - |
| `X-Request-Id` | Every error |
| `WWW-Authenticate` | 401 and 403. See [Authentication](https://docs.pinakelai.com/authentication.md#when-authentication-fails). |
| `Retry-After` | 429 and 503, in seconds |
| `RateLimit`, `RateLimit-Policy` | Errors on authenticated requests |

## Errors from the edge

Requests stopped before they reach the API, by Pinakel's edge protection or by the network, can get a status without a problem document: typically a 429 or 403 with an HTML or empty body, or a 502. Handle them by status code; [Handling errors](https://docs.pinakelai.com/guides/errors.md#errors-without-a-problem-body) shows how.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.