---
title: "Errors | Nuvio Docs"
description: "How the Nuvio API reports a request that failed, and what each status means."
url: https://nuvio.io/docs/api/errors
---

# Errors

The Nuvio API uses conventional HTTP response codes. Codes in the `2xx` range mean the request worked. Codes in the `4xx` range mean it failed because of what was sent: a missing or wrong key, a missing field, a record that doesn't exist. Codes in the `5xx` range mean an error on Nuvio's side; these are rare.

A failed request answers `success: false` and an `errors` array. Each entry has a `code`, a stable number your code can branch on, and a `message` in English for people. Don't parse the message: its wording can change.

## The error object

-   `success`boolean

    Always `false` on an error.

-   `errors`array of objects

    One entry per problem. A validation failure lists every rule that failed.

    -   `code`string

        The error's number, such as `1001`. Use it to handle a specific error.

    -   `message`string

        What went wrong, in English.

    -   `title`string, optional

        A short heading for the message, when there is one.

## HTTP status codes

`200`

OK. The request worked; the record or list is in data.

`400`

Bad request. The request breaks a rule of the endpoint, such as a missing id or an invalid status value.

`401`

Unauthorized. No usable API key was sent (1002).

`403`

Forbidden. The API key is unknown, or lacks the endpoint's scope (1001).

`404`

Not found. The record doesn't exist in the key's company.

`409`

Conflict. The record clashes with one that exists, such as a code, name or invoice number already in use.

`422`

Unprocessable. The body didn't pass validation; each failed rule is one entry in errors.

`429`

Too many requests. The company passed its limit of 1,000 requests an hour. Wait and try again.

`500`

Server error. Something went wrong on Nuvio’s side (5999). Try again later.

A `429` answers a plain-text body, `Too many requests. Please try again later.`, not the JSON envelope.

Error response · 403

```
{
  "success": false,
  "errors": [
    {
      "code": "1001",
      "message": "Access token has insufficient permissions to access this resource."
    }
  ]
}
```

Error response · 401

```
{
  "success": false,
  "errors": [
    {
      "code": "1002",
      "message": "Your request requires a valid access token. Please provide a valid token to proceed."
    }
  ]
}
```