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

• successboolean

  Always false on an error.

• errorsarray of objects

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

  • codestring

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

  • messagestring

    What went wrong, in English.

  • titlestring, 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."
    }
  ]
}