# Errors and limits

Source: https://developers.novilabs.com/forecasts/guides/errors-and-limits/

> The error envelope, what each status means, the size and concurrency limits, and how to back off.

Every error from the API has one shape, and the status tells you
what to do next.

## The error envelope

```json
{
  "error": {
    "code": "invalid_argument",
    "message": "wells[0].tvd isn't a known field; did you mean tvd_ft?",
    "details": { "field": "wells[0].tvd" }
  },
  "request_id": "3c9d1e7a-2b4f-4a6c-9d8e-7f1a2b3c4d5e"
}
```

- `code` is one of `invalid_argument`, `not_found`, `conflict`, `unavailable` and `internal`.
- `details.field` names the input at fault. Some errors add more, such as `details.allowed` with the values a
  parameter takes.
- `request_id` is the call's `X-Request-Id`. Quote it when you ask Novi about a call.

## Status codes

| Status | `code` | Means | Do |
| --- | --- | --- | --- |
| `400` | `invalid_argument` | An input is invalid. | Fix the field `details.field` names. |
| `401` | | No valid token. | See below. |
| `403` | `invalid_argument` | The user lacks access to Forecasts. | Ask your Novi administrator. |
| `404` | `not_found` | No such well, plan, export or path, or it belongs to another company. | Check the id. |
| `405` | `invalid_argument` | The path has no operation for that method. | Use a method from the `Allow` header. |
| `409` | `conflict` | The request conflicts with the state of what it names: a plan still running or failed, a read or change a Legacy Forecast doesn't support, a reused `Idempotency-Key` with another body, a full export queue. | Read `message`; wait or change the request. |
| `410` | `not_found` | An export's file expired. | Run the export again. |
| `413` | `invalid_argument` | The request body is too large. | Send less, or split it. |
| `416` | `invalid_argument` | A download range starts past the end of the file. | Restart the download. |
| `429` | `conflict` | Your queued and running plans would pass your cap. | Wait for `Retry-After`, or for a plan to finish. |
| `500` | `internal` | An unexpected error. | Retry once; then quote `request_id`. |
| `502` | `internal` | A model step failed. | Retry with the same `Idempotency-Key`. |
| `503` | `unavailable` | A model step or the grids aren't ready. | Retry shortly with the same `Idempotency-Key`. |

A missing, expired or revoked token gets `401` with the body `{"code": 401, "message": "Unauthorized"}` and no
`request_id`. A sign-in made for an MCP client gets `403` on the REST API. See
[Authentication](https://developers.novilabs.com/forecasts/authentication/).

Other statuses you will see: `202` when a job starts, `304` when an `If-None-Match` read finds nothing changed, and
`307` when an export download redirects to its signed copy.

## Limits

`GET /dataset` `limits` and `GET /export-formats` `limits` report most limits. Read them rather than hard-coding these
defaults.

| Limit | Value | Past it |
| --- | --- | --- |
| Drawn wells per `POST /forecasts` | 50 (`limits.forecast_wells`) | `400` |
| Designs per `POST /forecasts` | 25 | `400` |
| Wells × designs with `explain: true` | 10 | `400` |
| Forecasts (wells × designs) per plan | `limits.plan_wells`, up to 50,000 | `400` |
| One caller's unfinished plan forecasts | `limits.plan_unfinished_forecasts` | `429` with `Retry-After` |
| Async forecasts running, per company | 50 | `409` with `Retry-After: 1` |
| Plan economics jobs running, per company | 4 | `409` with `Retry-After: 1` |
| Exports queued or running | 20 per model set, 3 per plan | `409` |
| Request body, `POST /plans` | 64 MB | `413` |
| Request body, `POST /exports` | 10 MB | `413` |
| A file of areas (shapefile, GeoJSON, KML) | 10 MB, 5,000 areas | `413` or `400` |
| Plans per `GET /plans` page | 1 to 100, default 20 | `400` |
| Wells per curves page | 1 to 200, default 100 | `400` |
| `wait` on a job | 1 to 25 seconds | `400` |

## Backing off

- Honor `Retry-After` on `429` and `409`.
- Retry `502`, `503` and `504`, and a lost response, with the same `Idempotency-Key` so a retry never starts a second
  job. See [Jobs, waiting and retries](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/).
- Prefer `wait=25` on a job's `GET` to a polling loop.

## Rate limit headers [Planned]

The API sends no request-rate headers today. Standard `RateLimit` and `RateLimit-Policy` headers, so a client can pace
itself, are planned.
