Skip to content
Developers
Get an API token

Errors and limits

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

View MarkdownOpen in Claude(opens in a new tab)

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

{
"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 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.

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.

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
  • 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.
  • Prefer wait=25 on a job’s GET to a polling loop.

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