# Errors

| code | HTTP | retryable | meaning and recovery |
|---|---|---|---|
| `INVALID_INPUT` | 400 | false | The body is not valid JSON or is not an object. |
| `VALIDATION_FAILED` | 422 | false | A parameter is out of range, of the wrong type, or not an allowed enum value. error.details lists each issue. |
| `UNSUPPORTED_MARKET` | 422 | false | market/currency other than US/USD was requested. This service only covers the US market in USD. |
| `NOT_FOUND` | 404 | false | An explicit variant_id does not exist in the published catalog. |
| `DATA_VERSION_CHANGED` | 409 | true | expected_data_version no longer matches the published catalog. Re-run the original query without expected_data_version (keep your hard conditions) and continue with the new version. |
| `INVALID_CURSOR` | 400 | false | The cursor is malformed or belongs to a different query. |
| `UNAUTHENTICATED` | 401 | false | An API key was sent but it is unknown or malformed. Omit the key to use the anonymous trial. |
| `FORBIDDEN` | 403 | false | The key is valid but revoked or lacks access to this resource (for example admin endpoints). |
| `RATE_LIMITED` | 429 | true | Per-minute or per-day quota exhausted. Wait retry_after_seconds (also sent as Retry-After). |
| `PAYLOAD_TOO_LARGE` | 413 | false | Request body exceeds 16 KB. |
| `METHOD_NOT_ALLOWED` | 405 | false | Wrong HTTP method for this endpoint. |
| `INTERNAL_ERROR` | 500 | true | Unexpected server error. Safe to retry once; include request_id when reporting. |
| `SERVICE_UNAVAILABLE` | 503 | true | The database or a dependency is temporarily unavailable. |

Business outcomes are not errors: NO_MATCH_IN_COVERED_CATALOG, INSUFFICIENT_EVIDENCE, NEEDS_VARIANT, NO_OFFER_COVERAGE, OUT_OF_SCOPE and EMPTY_CATALOG come back with HTTP 200 and `success:true`.

Example:

```json
{"success":false,"error":{"code":"DATA_VERSION_CHANGED","message":"The catalog changed from c1.o0 to c2.o0. Re-run the original query without expected_data_version, keeping your hard conditions, then continue with the new data_version.","retryable":true},"result":{"expected_data_version":"c1.o0","current_data_version":"c2.o0"}}
```