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

# Errors

## The envelope

Every refusal the API itself makes has one shape:

```json theme={null}
{"error": {"code": "invalid_request", "message": "query.limit: Input should be greater than or equal to 1", "request_id": "206a3634962a476f9c4251f83de92612"}}
```

* `code` is machine-readable. The reference's `x-known-codes` lists the codes this version sends. A new
  code may be added at any time: handle an unknown code by its HTTP status.
* `message` is for people. Never parse it.
* `request_id` equals the `X-Request-Id` header. Quote it when you ask for help.
* Every operation's 200 and every enveloped refusal carries `Cache-Control: no-store` (the reference document at `/public/v1/openapi.json` does not).

## Codes

| status | code | meaning |
| - | - | - |
| 401 | unauthorized | no key, or a key that is unknown, revoked or expired |
| 403 | access\_not\_granted | API access is free but granted on request; request it on [https://trendlinelabs.ai/developer](https://trendlinelabs.ai/developer) |
| 403 | tier\_required | the key owner's plan does not include API access |
| 403 | insufficient\_scope | the key lacks the scope this route needs |
| 403 | ip\_not\_allowed | the request came from outside the key's allowlist |
| 404 | not\_found | no such event, market or key |
| 404 | venue\_not\_listed | the market has no leg on that venue |
| 409 | key\_limit\_reached | key management: the account holds as many keys as it may |
| 410 | market\_closed | the market's leg on that venue no longer trades |
| 422 | invalid\_request | a parameter is missing, unknown, malformed or out of bounds, or a cursor does not match |
| 422 | venue\_unsupported | the route does not serve that venue |
| 422 | scope\_unavailable | key management: a scope named at creation is not available |
| 429 | rate\_limited | too many requests, or too many failed authentications; wait `Retry-After` seconds |
| 500 | internal\_error | an unexpected failure on our side; quote the request id |
| 503 | dependency\_unavailable | one of our own stores could not be read; retry later |
| 503 | upstream\_unavailable | the data source is unreadable, absent or older than its bound |

A dead or stale source is always a 503, never an empty 200.

Key management (`/api/v1/developer/keys`, used from the website) sends access\_not\_granted, tier\_required, rate\_limited,
dependency\_unavailable, not\_found, invalid\_request, scope\_unavailable and key\_limit\_reached in the
same envelope.

## Example

```json theme={null}
{"error": {"code": "not_found", "message": "no such event", "request_id": "8f1a8d36dd7f4482826a9e3687048e44"}}
```

## Bodies that are not the envelope

A few answers come from the web server rather than the API, and are not enveloped:

| when | status | body |
| - | - | - |
| an unknown path under `/public/`, or a trailing slash | 404 | `{"detail": "Not Found"}` |
| a method other than GET | 405 | `{"detail": "Method Not Allowed"}` |
| HEAD | 405 | empty |
| a browser preflight from another site, or from the documentation site for a method other than GET or HEAD or a header other than `Authorization` and `Content-Type` | 400 | text/plain `Disallowed CORS origin` (or `method`, `headers`) |
| a failure that escapes a route's own handling, on `/opportunities`, `/events/{universal_id}`, `/markets/search`, `/prices/snapshot` and `/key` | 500 | text/plain `Internal Server Error`, with no `X-RateLimit-*` headers |
| key management without a signed-in session | 401 | `{"detail": ...}` |
| key management with a malformed body | 422 | `{"detail": [...]}` |

Treat any 5xx you cannot parse as internal\_error.


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