# Errors and recovery

Section: Reference
Source: https://platform.metix.ai/docs/reference/errors
Every page in one file: https://platform.metix.ai/llms-full.txt

Public API failures use one response envelope so clients can tell validation, authentication, quota, rate-limit, and server outcomes apart.

## Error shape

```json
{
  "code": 422,
  "msg": "Invalid parameter format or value",
  "data": null
}
```

## HTTP status reference

| HTTP | Meaning | Client action |
| --- | --- | --- |
| 400 | Invalid or missing request parameters, including a refused query tree | Correct the request before retrying |
| 401 | Missing or invalid API key | Provide a valid Bearer key |
| 402 | Credits exhausted | Review quota and plan state |
| 403 | Key disabled, expired, or missing scope | Use an active key with the required scope |
| 404 | Route or selected record not found | Check the path or omit unavailable records |
| 422 | Invalid parameter format or value | Fix the named field |
| 429 | Rate limit exceeded | Back off before retrying |
| 500 | Internal server error | Retry only with bounded backoff |
| 503 | Capability unavailable | Treat the feature as unavailable |

## Query Spec refusals

A query tree is translated before anything runs, so these all arrive as a 400 and none of them cost a Credit. The [Query Spec page](https://platform.metix.ai/docs/api/query-spec.md) explains the grammar behind each one.

| Message | What triggered it | Fix |
| --- | --- | --- |
| At least one search condition is required. | An empty where tree | Add a condition. An unfiltered sweep of the corpus is not available |
| Unsupported query field. See the documented field list. | A field name that is not in this dataset's list | Check the dataset's field table. The three datasets do not share one vocabulary, so a name from another one is refused here |
| Unsupported operator. Allowed: eq, in, match, gte, lte, exists. | Two operators in one leaf, no operator, an operator the field does not accept, or a number sent as a string | One operator per leaf, matched to the field kind. Split a bounded range into an all of two leaves |
| Each query node must be one of: all, any, not, a scope, or a field condition. | A node shape the grammar does not have, or an extra key on a leaf | Remove the extra key, or wrap the conditions in a composer |
| Unsupported date value. Use YYYY-MM-DD or a documented relative value such as now-6m. | A date form outside the documented set, or an offset past the maximum | Use YYYY-MM-DD, or now-<n>d, now-<n>m, now-<n>y inside the published limits |
| Field is not available inside <scope>. | A field used inside a scope that does not group it | Move the condition outside the scope, or use a field the scope covers |
| Nested scopes cannot be nested inside one another. | has_experience inside has_education, or similar | Keep scopes at the same level and combine them with all or any |
| Query nesting exceeds the maximum depth of 6. | A tree nested deeper than six levels | Flatten the tree. Most queries need two or three levels |
| Query exceeds the maximum of 64 conditions. | More than 64 leaves in one tree | Split the work across several queries, or use in with a list instead of many any branches |