In the Bokio API, standard HTTP status codes are used to indicate errors. These status codes provide a standardized way of communicating the outcome of a request. In addition to the status code we provide both a human-readable message field and code field that can be used for machine interpretation of the error. A bokioErrorId is included for Bokio to better be able to help you if you need assistance.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "error": {
    "code": "string",
    "innerCode": "string",
    "message": "string",
    "bokioErrorId": "string"
  }
}

Common error codes are specified in Error codes, but please explore the API operation that you use because there you'll find detailed information on which error codes to expect for the specific operation.

HTTP Status Codes

The following HTTP status codes are commonly used in the Bokio API for error handling:

400 Bad Request: The request was invalid or could not be understood by the server.
401 Unauthorized: The request requires authentication, but the user is not authenticated.
403 Forbidden: The server understood the request, but refuses to authorize it.
404 Not Found: The requested resource could not be found.
426 Upgrade Required: The request is made on an endpoint which version is nearing the sunset date. Scheduled brownouts are used to nudge the application to upgrade, see Brownout periods
429 Too Many Requests: The request was not processed as rate limits have been surpassed. See Rate Limits.
500 Internal Server Error: An unexpected error occurred on the server.

It is important to handle these status codes appropriately in your application to provide a good user experience.

Error codes

Below we list the most common error codes and how they are formatted

Not found

{
  "message": "The requested resource was not found",
  "code": "not-found",
  "bokioErrorId": "2f3fa960-3def-45ce-8cf3-28d33ac76fd7"
}

Validation error

{
  "message": "Validation failed with 1 error",
  "code": "validation-error",
  "bokioErrorId": "2ddf3c8f-c83a-4eb2-a28f-8f6f50425947",
  "errors": [
    {
      "field": "#/lineItems/0/taxRate",
      "message": "The tax rate field must be one of the following values: 0%, 6%, 12%, or 25%"
    }
  ]
}

Internal server error

{
  "message": "An unexpected error occurred",
  "code": "internal-server-error",
  "bokioErrorId": "2f3fa960-3def-45ce-8cf3-28d33ac76fd7"
}

Operation not allowed

{
  "message": "The invoice a419cf69-db6f-4de9-992c-b1a60942a443 could not be updated because it was not in draft state",
  "code": "operation-not-allowed",
  "bokioErrorId": "3fd4d194-5361-4876-a641-cc5cb98fd548"
}

Limit exceeded

{
  "message": "File size too large",
  "code": "limit-exceeded",
  "bokioErrorId": "2f3fa960-3def-45ce-8cf3-28d33ac76fd7"
}