# Errors

Every /v2 error, what it means and what to do about it.

Every error body is `{"code": "...", "message": "..."}`, plus `details` for the codes that list it. Branch on `code`. The wording of `message` can change. See [Handle errors and retries](../guides/errors-and-retries.md).

## Fix the request

Don't retry these unchanged.

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 400 | `invalid_request` | Fails the schema, or has unknown fields or parameters | Fix the request. |
| 400 | `unsupported_profile` | Profile not offered by this deployment | Read `routing.profiles` from `/v2/info`. |
| 400 | `too_many_points` | More than 10 route points | Split the trip. |
| 400 | `too_many_cells` | Matrix over 25 cells | Split the matrix. |
| 401 | `unauthorized` | Missing or invalid API key | Send a valid `X-API-Key`. |
| 403 | `forbidden` | Not allowed, including a wrong HTTP method | Use the documented method. |
| 403 | `trial_unavailable` | Keyless trial call without a valid trial session | Send an API key. |
| 403 | `trial_exhausted` | The 5 keyless trial runs for today are used up | Use a key, or wait for the next Philippine day. |
| 404 | `not_found` | Unknown `/v2/...` path | Check the endpoint name. |
| 413 | `payload_too_large` | Body over 32 KB | Send less. |
| 415 | `unsupported_media_type` | POST body not declared as JSON | Send `Content-Type: application/json`. |

## Change the points

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 422 | `point_not_snapped` | A point has no road within 1 km (`details.point_index`) | Move the point to within 1 km of a road. |
| 422 | `out_of_coverage` | A point is outside `coverage.bbox` (`details.point_index`) | Check the point and its `[lng, lat]` order. |
| 422 | `no_route` | No path between the points, or an engine limit was hit | Tell the user, or try nearer points. |
| 422 | `reference_not_found` | `near_text` found nothing | Rephrase it, or use `near`. |

## Retry with backoff

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 429 | `rate_limited` | Over the rate limit | Wait for `Retry-After`, then retry. |
| 500 | `internal_error` | An unrecognised engine reply, or a bug | Retry once, then report it. |
| 503 | `engine_unavailable` | An engine is down | Retry with backoff. |
| 503 | `unavailable` | The API service is unreachable | Retry with backoff. |
| 504 | `engine_timeout` | An engine did not answer in time | Retry with backoff, then give up. |

## Don't retry

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| 429 | `data_cap_exceeded` | Your [monthly data cap](../concepts/known-limits.md#your-key) is reached | Email [contact@sieitz.com](mailto:contact@sieitz.com) to raise it. Requests work again when the month ends (UTC). |
| 501 | `capability_unavailable` | This deployment doesn't offer the feature (`details.capability`) | Read `capabilities` from `/v2/info`. |