Overview

The Regate API uses standard HTTP response codes to indicate the success or failure of an API request. Overall:

Codes in the 2xx range indicate a successfully processed request.
Codes in the 4xx range indicate that there was an error with the request (e.g. unauthorized access, missing required attribute, etc.).
Codes in the 5xx range indicate that there is an issue with Regate's servers. Those are quite rare.

List of error codes

Status code	Reason	Description
`200`	`OK`	Successful operation. Congratulations!
`201`	`Created`	Returned when a `POST` request was successful.
`202`	`No Content`	Returned when a `DELETE` request was successfully processed.
`401`	`Unauthorized`	Invalid authentication credentials, or the user has insufficient rights to perform the requested action.
`403`	`Forbidden`	Triggered when the user has sent too many requests in a given amount of time. See Rate limiting for more details.
`404`	`Not found`	The URL has not been found.
`406`	`Not acceptable`	The resource exists, but the response cannot be returned in the format specified in the `Accept-` header.
`422`	`Unprocessable Entity`	The payload contains attribute values which contradict the Regate application logic. For example, a request to create an invoice where the total amount is lower than the VAT amount in the payload will be declined with this error code.
`500`	`Internal server error`	There is an issue on our side and we apologize. These types of errors will contain an error identifier in its description. Please contact our support team, providing the error identifier, and we will do our best to help.

Error response format

Depending on the error code that is being returned, the response formats may vary. Below we will list examples of the responses.

401 - Unauthorized

The errors array in the response will contain a string value explaining the error message - in this case "Access denied"

{
    "errors": [
        "Access denied"
    ]
}

403 - Forbidden

The response body will contain an error attribute, as well as error_description, providing information on why it was triggered.

{
    "error":"too_many_attempts",
    "error_description":"You have made too many attempts in a given amount of time."
}

404 - Not found

The errors array in the response will contain two attributes:

message - containing a description of the error
status - providing the status code, in this case 404

{
    "errors": [
        {
            "message": "Couldn't find CustomerInvoice with 'id'=123456789",
            "status": 404
        }
    ]
}

406 - Not acceptable

The response body is empty.

422 - Unprocessable entity

The response body may contain a number of attributes, depending on the amount of mistakes in the request body. Each attribute in the response is an array and has the name of the attribute in the request body which triggered an issue. The values in the array indicate the error descriptions for that attribute.

{
    "currency": [
        "is not included in the list"
    ],
    "customer_id": [
        "can't be blank"
    ],
    "due_date": [
        "can't be blank",
        "must be a valid date (e.g. 2023-01-31)"
    ],
    "lines": [
        "can't be blank",
        "must be an array"
    ]
}

500 - Internal server error

The response body will contain two attributes:

status - providing the error status code, in this case 500
error - containing a description of the error

{
    "status": 500,
    "error": "Internal Server Error"
}