# Errors

Source: https://developers.novilabs.com/platform/errors/

> The error shape, status codes and request ids of each Novi product, and what to do about common errors.

Each product returns errors in its own shape today.

## At a glance

| Product | Error shape | Request id |
| --- | --- | --- |
| Novi UDM Data over HTTPS | Snowflake's SQL API responses | Snowflake's `statementHandle` |
| Novi Forecasts API | `{"error": {"code", "message", "details"}, "request_id"}` | `X-Request-Id` header and `request_id` |
| Novi EVA REST API | `{"error": "<message>"}` | Not published yet |
| Novi EVA MCP server | Tool error `{"code", "message", "retryable", "field"}` | Not published yet |
| Novi M&A Intelligence MCP server | A tool result whose message names the cause | Not published yet |
| Novi sign-in on company hosts | `401` or `403`. On the Forecasts API the `401` body is `{"code": 401, "message": "Unauthorized"}` | None |

## Novi UDM Data (v4)

Over HTTPS, Novi UDM Data answers through Snowflake's SQL API. A statement still running answers `202`; check it with `GET /api/v2/statements/<statementHandle>`. A failed statement answers `422`. Snowflake documents both at docs.snowflake.com/en/developer-guide/sql-api/handling-responses.

| What you see | Cause | Do |
| --- | --- | --- |
| A permission error on a view, on your own Snowflake account | The role lacks Novi's database role | Your administrator grants `DR_WELLS_STANDARD` or `DR_WELLS_FULL` to that role |
| `CREATE DATABASE` fails in the setup script | Outside AWS us-east-2, the listing can take a few hours to appear the first time | Wait and run the script again |
| The first query waits 10 to 30 seconds | The reader-account warehouse was idle | Nothing. Later queries run at once |
| A statement stops after 2 hours | The time limit on a BI or lakehouse connection | Narrow the query |

## Novi Forecasts API

```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"
}
```

| Status | `code` |
| --- | --- |
| `400`, `401`, `403`, `405`, `413`, `416` | `invalid_argument` |
| `404`, `410` | `not_found` |
| `409`, `429` | `conflict` |
| `500`, `502` | `internal` |
| `503` | `unavailable` |

`details.field` names the input at fault. A sign-in made for an MCP client gets `403` on the REST API. Full table and what to do: [Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/).

## Novi EVA REST API

| Status | Body |
| --- | --- |
| `401`, no key | `{"error": "Missing x-api-key header"}` |
| `401`, invalid key | `{"error": "Invalid API key"}` |
| `400`, too many wells | `{"error": "Too many wells requested. Limited to 50,000 at a time."}` on `POST /v1/data` |

In a result, `"n/a"` means a value is not available and `"Subscription Required"` means your subscription does not include it. Neither is an error.

## Novi EVA MCP server

| Code | Retry |
| --- | --- |
| `LIMIT_EXCEEDED` | When `retryable` is true; otherwise narrow the request |
| `DEADLINE_EXCEEDED` | Yes, or narrow the filter |
| `DEPENDENCY_ERROR` | Later. A failed read is never reported as zero |
| `INVALID_CURSOR` | Start again without a cursor |
| `VALIDATION_ERROR` | No. Fix the input `field` names |
| `UNSUPPORTED_OPERATION` | No. Check what `describe_columns` lists |
| `ACCESS_DENIED` | No. Do not retry with guessed columns |

Details: [EVA MCP server, errors](https://developers.novilabs.com/eva/mcp/).

## Novi sign-in

These apply to every product on a Novi company host.

| Status | Means | Do |
| --- | --- | --- |
| `401` | No token, or one that expired or was revoked | Create a new token, or sign in again |
| `403` | The token is not valid for this path: wrong product, wrong company, a sign-in token on a REST API, or a missing permission | Use the right credential; ask your administrator for the permission |
| `503` | Novi could not check your token or sign-in just then | Retry |

## Planned

| Item | Status |
| --- | --- |
| One error format across APIs, RFC 9457 problem details | [Planned] |
