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, when possible, both a human-readable and machine-readable JSON body.

HTTP Status Codes

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

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

Bokio error body

The Bokio error body provides additional information about an error. By using JSON Pointer it's possible to narrow down which field in the request body that was wrong. For example, a #/lineItems/1/quantity tells you that the error is specifically for quantity field on the second line item in the request body.

    apiError:
      type: object
      title: apiError
      description: |
        Represents an error response from the API with details about the error(s). 
        
        The `errors` array contains specific validation errors, each with a `message` and a `resource` to the field that caused the error. This array will be empty for other types of errors.
      required:
        - message
        - code
        - bokioErrorId
      properties:
        message: 
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              field:
              	description: JSON Pointer to the incorrect element
                type: string 
        bokioErrorId:
          type: string
          format: uuid
      example:
        code: "ValidationError"
        message: "The request contains invalid data."
        errors:
          - message: "The 'name' field is required."
            field: "#/data/attributes/1/name"
          - message: "The 'email' field must be a valid email address."
            field: "#/data/attributes/0/email"
        bokioErrorId: "123e4567-e89b-12d3-a456-426614174000"

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.

Error codes

OAuth errors

For OAuth related endpoints /authorize and /token the Bokio API following the OAuth 2.0 specification. These errors will either come as a 302 to the specified redirect_uri but can also be return as a response from the endpoint. In those cases it would normally come in form of 400.