Errors
In this page we'll explain how to manage the errors that could arise while using our APIs. Our APIs use conventional HTTP status codes to indicate the result of a request.
The request codes can be categorized in this way:
- 2xx codes indicate success
- 4xx codes indicate a client error
- 5xx codes indicate a server error
Each error comes with a payload that describes what has occurred. The response body may be structured in different ways, depending on the error type.
Below you can find a list of the error codes used by the Fatture in Cloud APIs:
| Code | Title | Meaning |
|---|---|---|
| 401 | Unauthorized | The token is missing, invalid or expired. To fix this, you should re-authenticate. |
| 403 | Forbidden | The user or the token you’re using does not have the right permissions to fulfill the request. This can also happen if the license is expired or if you’ve reached the API usage limits. |
| 404 | Not Found | The resource you are looking for does not exist. |
| 409 | Conflict | Cannot perform the operation. |
| 422 | Unprocessable Entity | The request is invalid. This can happen if the body of the request does not pass validation. |
| 429 | Too Many Requests | Your application is making too many requests and has exceeded the quotas. You should wait for the number of seconds specified in the Retry-After response header before trying again. |
| 5xx | Server Errors | An error occured on Fatture in Cloud’s servers. These errors are rare. If you encounter one of these, please contact us. |
🙅♂️ Authentication errors
When authenticating using OAuth 2.0 Authentication Code Flow, you may encounter errors as described by the standard.
During the authorization phase, any errors are included in the redirect URL as query string parameters. Keep in mind that if is not possible to complete the redirect (for example if you provided an invalid redirect URL) the error will be shown directly on the Fatture in Cloud authorization page, so you'll not receive a callback with the error parameters.
You can consult the complete list of errors here, in the Error Response section.
When requesting an Access Token using an authorization code or a refresh token, errors are sent in the response body like in the example below:
HTTP/1.0 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_request",
"error_description": "The code field is required when grant type is authorization_code."
}
If you decided to use the OAuth 2.0 Device Authentication Flow, some errors are embedded in the polling part of the flow by default (you can check the list here), so you won't be able to avoid them; this means that you need to manage them in your code to perform obtain authorization to use our APIs.
The errors to manage are returned in these cases:
| Error | Expected behaviour |
|---|---|
| slow_down | Your polling frequency is too high, decrease the ratio a little. |
| authorization_pending | The user has yet to approve your request. Check again later. |
| access_denied | The user refused the request for permissions made by your application. |
| expired_token | The user took too much to complete the authorization process, and the code expired. Your application can immediately ask for a new device code. |
🙋♂️ Client errors
Other errors that do not involve authorization or permissions, for example as a result of an invalid request or due to a non-existent resource, generate a response with an error object containing all the parameters useful to resolve the issue. This object contains a message and may contain a code parameters. Errors due to validation issues will include the validation_result object, which contains the list of the fields that generated the error and an explanatory message.
HTTP/1.0 404 Not Found
{
"error": {
"message": "La risorsa richiesta non esiste."
}
}