# Errors and versioning

Handle errors, retry safely and keep your integration compatible.

REST errors have a stable envelope:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be an integer.",
    "request_id": "<request UUID>"
  }
}
```

| Status | Meaning | Next step |
| --- | --- | --- |
| 400 | Invalid or unsupported parameters | Check the schema and parameter names. |
| 401 | Invalid API key | Replace, rotate or omit the key. |
| 404 | Unknown endpoint or record | Use IDs returned by search; records can disappear. |
| 405 | Unsupported method | Use GET for market data; POST for the CV checker and MCP. |
| 413 | MCP request body exceeds 450,000 bytes | Send a smaller request. |
| 429 | Rate limited | Wait at least Retry-After seconds and reduce concurrency. |
| 503 | Service unavailable | Retry with backoff; keep previous results labelled with their last checked dates. |

Include `X-Request-Id` when reporting an API failure. Search responses may reuse a backend cache; Panta adds no additional public cache window.

The public contract is versioned at `/api/v1`. Clients should tolerate new fields and new nullable values. Breaking contract changes require a new major API path. The older `/api/search/*` routes remain used by the website; new integrations should use v1. Market-data MCP tools follow the v1 contract. Workspace MCP tools are separately permissioned account operations. The public CV checker is an independent POST endpoint; its limits are documented in the [checker API guide](https://withpanta.com/docs/cv-checker/).