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
Section titled “The error envelope”{ "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"}codeis one ofinvalid_argument,not_found,conflict,unavailableandinternal.details.fieldnames the input at fault. Some errors add more, such asdetails.allowedwith the values a parameter takes.request_idis the call’sX-Request-Id. Quote it when you ask Novi about a call.
Status codes
Section titled “Status codes”| Status | code |
Means | Do |
|---|---|---|---|
400 |
invalid_ |
An input is invalid. | Fix the field details. names. |
401 |
No valid token. | See below. | |
403 |
invalid_ |
The user lacks access to Forecasts. | Ask your Novi administrator. |
404 |
not_ |
No such well, plan, export or path, or it belongs to another company. | Check the id. |
405 |
invalid_ |
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_ |
An export’s file expired. | Run the export again. |
413 |
invalid_ |
The request body is too large. | Send less, or split it. |
416 |
invalid_ |
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_. |
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.
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
Section titled “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 / |
50 (limits.) |
400 |
Designs per POST / |
25 | 400 |
Wells × designs with explain: true |
10 | 400 |
| Forecasts (wells × designs) per plan | limits., up to 50,000 |
400 |
| One caller’s unfinished plan forecasts | limits. |
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 / |
64 MB | 413 |
Request body, POST / |
10 MB | 413 |
| A file of areas (shapefile, GeoJSON, KML) | 10 MB, 5,000 areas | 413 or 400 |
Plans per GET / 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
Section titled “Backing off”- Honor
Retry-Afteron429and409. - Retry
502,503and504, and a lost response, with the sameIdempotency-Keyso a retry never starts a second job. See Jobs, waiting and retries. - Prefer
wait=25on a job’sGETto a polling loop.
Rate limit headers Planned
Section titled “Rate limit headers ”The API sends no request-rate headers today. Standard RateLimit and RateLimit-Policy headers, so a client can pace
itself, are planned.