Errors

This page explains how to handle errors that may occur when using the Sibill APIs. The APIs use the HTTP status code convention to indicate the result of a request. Status codes can be categorized as follows:

• 2xx codes: indicate the request was successful
• 4xx codes: indicate a client error
• 5xx codes: indicate a server error

Every error includes a payload that describes what happened. Below is a list of the HTTP status codes used by the APIs:

HTTP Code	Meaning	Description
200	OK	Everything worked as expected.
201	Created	The resource was successfully created.
400	Bad Request	The request is not acceptable, often due to a missing required parameter.
401	Unauthorized	No valid API key was provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key does not have permission to perform the request.
404	Not Found	The requested resource does not exist.
422	Unprocessable Entity	The request was understood but cannot be processed due to semantic errors.
500, 502, 503, 504	Server Errors	A problem occurred while Sibill was handling the request.

🙅‍♂️ Authentication errors

When using token-based authentication, you may receive an error if the token is invalid or was not provided.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
   "errors":[
      {
         "code":"unauthorized",
         "detail":"Authentication failed.",
         "title":"Unauthorized"
      }
   ]
}

If the token is valid but does not have the necessary permissions to perform the request, you will receive a 403 error.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
   "errors":[
      {
         "code":"forbidden",
         "detail":"Forbidden.",
         "title":"Forbidden"
      }
   ]
}

To quickly check whether the token is valid, you have access to the endpoints, or if there is a network issue, you can try the following command:

curl --request GET \
     --url {{BASE_URL}}/api/v1/companies \
     --header "Authorization: Bearer {{TOKEN}}"

Errors caused by validation issues will include a source object containing the list of fields that generated the error.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "errors":[
      {
         "code":"bad_request",
         "detail":"Invalid integer. Got: string",
         "title":"Invalid value",
         "source":{
            "pointer":"/page_size"
         }
      }
   ]
}

🖥️ Sibill server errors

Other errors that are not caused by authentication or client request issues, but by internal server problems, generate a response with an error object describing the issue.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
   "errors":[
      {
         "code":"internal_server_error",
         "detail":"An unexpected error occurred.",
         "title":"Internal Server Error"
      }
   ]
}