Skip to main content

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:

CodeTitleMeaning
400Bad RequestThe request was malformed, and our APIs could not process it.
401UnauthorizedThe user is not authorized to perform this operation.
403ForbiddenThe user or the token you’re using does not have the right permissions to fulfill the request. This can also happen if the license has expired or if you’ve reached the API usage limits.
404Not FoundThe resource you are looking for does not exist.
405Method Not AllowedThe HTTP Method is not allowed on this endpoint.
409ConflictCannot perform the operation, probably due to a conflict on the existing resources.
422Unprocessable EntityThe request is invalid. This can happen if the body of the request does not pass validation.
429Too Many RequestsYour 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.
5xxServer ErrorsAn error occurred on Fatture in Cloud’s servers. These errors are rare. If you encounter one of these, please contact us.

📋  HTTP codes and examples​

Here you can find a list of the most common errors for each HTTP code:

⚠️  400 Bad Request​

We usually send this error when there was a problem while performing one of the OAuth 2.0 flows. This error response will follow the Authentication errors format, so you should read the error_description value to get an explanation of the error.

Some of the main causes are:

  • Missing or invalid token
  • Expired refresh token
  • Unsupported grant type

A special case of 400 errors is the one obtained while retrieving the Access Token in the OAuth 2.0 Device Code Flow; you can recognise these errors by checking if the error field is one of the ones listed in the dedicated page. In this case, the errors are part of the authorization code, because you will get at least one error while waiting for the user manual approval of your request. If you're implementing this authorization flow, you should be ready to manage this kind of error.
You can also check here for more info.

🔒  401 Unauthorized​

In this case, there was an authorization error on your request. It could be caused by a missing or invalid token, or the authenticated user may not have access to the resource. This error response could follow both the Authentication errors or API errors format, based on the specific error you're obtaining, so you must check both the error_description and the error.message fields.

Some of the main causes are:

  • Invalid Client ID or Secret
  • The Access Token is expired, revoked, malformed or invalid for other reasons
  • The user is unauthorized to access the requested resource, for example, because you specified a wrong Company ID
  • The client is not authorized to use this application
  • The user is banned

You will be able to solve most of these errors by checking your request, but two of these errors are special cases:

  • If your user is not authorized to use the application, it means that the app is Private and the user is not in the app's Whitelist; the owner of the app will be required to add your Fatture in Cloud account to the list on the Fatture in Cloud developer section. You can check the App Visibility section for more info.
  • If the user is banned, it means something bad happened, and the user cannot use Fatture in Cloud entirely. It could happen if our systems detect a suspicious action and ban the user to avoid bad consequences. If you're banned and you think you did nothing bad, you should contact our Customer Support immediately.

🚫  403 Forbidden​

In this case, your token is valid, and you also could have access to that resource, but there is some other problem that makes it impossible to fulfill the request. This error response follows the API errors format, so you must check the error.message field.

Some of the main causes are:

  • The token is lacking the permissions to perform the operation
  • The API Quota limit was reached
  • Your license has expired

The first error is the easiest to resolve: your token was created without the scope needed to perform the current request. If you're the developer, you must check your authorization flow to be sure that all the scopes needed were properly required; if you're just the final user, you should contact your integration's support.

If your quota limit was reached, it is a temporary error, and you must wait. Our APIs are protected by limits to avoid misuse, and you must wait until your quota is replenished. The response will also contain more info about when you'll finally be able to use our APIs again. You can check the dedicated page for more info: Limits and Quotas.

If your license has expired... well, it means you should check your Fatture in Cloud subscription; if you're currently using a trial license for development purposes, you can contact our support team to extend the trial license, explaining the situation.

🔍  404 Not Found​

In this case, you're trying to access a resource that doesn't exist. It could be that you're using a wrong ID, or that you're trying to access a resource that was deleted previously. This error response follows the API errors format, so you must check the error.message field.

🔨  405 Method Not Allowed​

This case is a little technical. It means that the resource (in this case, the URL) is valid, but you're trying to perform an operation that is not expected for the resource; the operations are defined by the HTTP Method you specify in the request.

For example, the following endpoint is used by the List Issued Documents and Create Issued Document operations: /c/{company_id}/issued_documents

These operations expect the GET and POST HTTP Methods, so if you try to use a DELETE method on this endpoint by mistake, you will obtain the 405 error.

Please note that the Delete Issued Document method uses a slightly different endpoint, so by adding the Document ID you will solve the error: /c/{company_id}/issued_documents/{document_id}

💥  409 Conflict​

In this case, your operation is formally valid, but there is some condition on Fatture in Cloud that makes it impossible to perform this operation; it is really important to check the error response, because you will find the detailed explanation of the current situation. This error response follows the API errors format, so you must check the error.message field.

The most common cause of a 409 error is that the resource you're trying to create already exists or conflicts with another one. For example, you will obtain this kind of error if you try to create an invoice with the same number as a previously existing one, or a new client with a tax code already inserted in the clients list.

A similar, but trickier one, is that the Fatture in Cloud documents must be chronologically sorted: if you already have the document number 5 with date 2026-03-20, you cannot create a new document 6 with date 2026-03-19; if the number is higher, you must use a date equal to or higher than, the other document's date.
Of course, the reversed situation is also true, I cannot create a new document 4 with date 2026-03-21 because the document number is lower but the date is higher than the already existing document's on date.

Some other causes could include:

  • The Electronic Invoicing service is not active on the FIC account
  • You reached your Plan Limits and cannot create more resources
  • The email address you specified was not configured to send the email
  • The document is locked, you cannot perform the operation (usually because it has already been sent to the SDI)
  • You're trying to send a document type that cannot be sent
  • You exceeded the email quota for a trial account
  • The creation or modification of a document is already being executed, please wait

The last error is special: it usually happens if you sent two or more requests in a really short amount of time, so our systems were not able to complete the first operation before taking charge of the others. You'll usually be able to retry the failed operation in a few seconds, but in some rare cases, the situation cannot be solved on its own, so if you continue seeing this error for a longer time, you should contact our Customer Support, because they could solve the situation for you.

✏️  422 Unprocessable Entity​

This error happens because your request has a validation issue, and it is impossible to proceed. This error response follows the API errors format, so you must check the error.message field; additionally, if the error is due to a field's format or to the e-invoice XML validation, you will find a more detailed description in the errors.validation_result array.

Some of the main causes include:

  • Wrong field type
  • XML validation error
  • Totals error (the amount to be paid differs from the payments total)

The Totals error is so frequent and tricky to solve that we decided to create a dedicated guide: Invoice Totals Calculation. You should read it in detail to avoid this situation. Also, to support the error resolution, the response will include an additional extra field, containing the details of the calculations we performed on our platform, so we suggest checking it when this error occurs.

⏳  429 Too Many Requests​

This error is the easiest to solve: you must slow down! This error can happen when you exceed the Rate Limits by sending a huge amount of requests in a short amount of time, so you just need to wait a little bit before retrying the request.

This error response follows the API errors format, but the error.message field will just explain that you sent too many requests. Luckily, this response also includes a header to indicate how much time you must wait before retrying, so you should check that value when a 429 error occurs.

The best way to deal with this kind of error is to adopt an exponential backoff strategy. You can check this guide for some code examples implementing this strategy.

🔥  500 Internal Server Error​

This error means that something bad happened on our side, so you should contact our support immediately. There is one special case where this could be solved without our support: if you inserted an unsupported character (like an emoji) in a field that doesn't support it, this could cause a 500 error, so you should try to solve it by sanitizing the field.

This error response follows the API errors format, so you must check the error.message field to understand what happened.

🏷  Error types​

Our errors can be grouped into two main categories, which follow two distinct error response formats. This means that if you want to manage the errors properly, you must be able to retrieve the error message and return it to the user of your integration.

Please note that some error codes (like the 401 Unauthorized code) use both the error formats, so you should be able to check which error format you're obtaining to extract the error message properly.

🙅‍♂️  Authentication errors​

If an error happens in the Authentication phase or while authenticating the request, you may encounter errors as described by the OAuth 2.0 standard.

This kind of errors will usually happen while performing the OAuth 2.0 Authorization Code or OAuth 2.0 Device Code steps, but they could also happen after you obtain the token if you fail to set it up correctly inside the API request.

The response for this error type will be something similar to this example:

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."
}

As you can see, the JSON response is really simple and contains an error field, containing a short code identifying the error, and an error_description field containing a detailed explanation.

The errors that could occur during the OAuth 2.0 Authorization Code flow are standardised, and you can consult the complete list here, in the Error Response section.

During the authorization phase, you redirect the user to the Fatture in Cloud page and don't perform any API request, so if an error occurs, you cannot receive any error response. The error details are thus included in the redirect URL as query string parameters, with the same field names used by the JSON counterpart. Keep in mind that if it 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.

warning

If you decided to use the OAuth 2.0 Device Code 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 obtain authorization to use our APIs.

We suggest you check the dedicated page for more info about how to manage this use case: OAuth 2.0 Device Code Flow

🙋‍♂️  API 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 in the API error format; these errors are typical of Fatture in Cloud, and so they use a dedicated structure. This error response type always contains an error object; this object will include all the details useful to resolve the issue.

The most basic version of the API errors includes the error.message field, describing the error that occurred, and may also contain an error.code field.

HTTP/1.0 403 Forbidden
{
   "error":{
      "message":"License expired.",
      "code":"LICENSE_EXPIRED"
   }
}

Errors due to validation issues could include the error.validation_result key-value map; this is usually included when it is necessary to identify the specific field that triggered the error.

HTTP/1.0 422 Unprocessable Entity
{
   "error":{
      "message":"Invalid request.",
      "validation_result":{
         "data.items_list.4.name":[
            "The data.items list.4.name must be a string."
         ],
         "data.items_list.4.description":[
            "The data.items list.4.description must be a string."
         ]
      }
   }
}

As you can see, the keys of the validation_result object will indicate the fields that did not pass validation, with each level separated by a point and the position in an array highlighted by its position in the list itself. Each key will correspond to an array containing one or more strings, describing the errors found on that single field.

When the error is due to an XML validation issue, the validation_result object will instead contain the xml_errors key, including all the errors found in this validation step.

HTTP/1.0 422 Unprocessable Entity
{
   "error":{
      "message":"Validation step 1",
      "validation_result":{
         "xml_errors":[
            "Il Codice Fiscale del cliente non è valido.",
            "La Partita IVA del cliente non è valida."
         ]
      }
   }
}

To help you resolve the Totals error, we return an additional extra.totals field, containing the calculations performed by Fatture in Cloud that led to the error. This field will contain the same structure as the Get New Issued Document Totals and Get Existing Issued Document Totals, so you can use it to replace those API methods if needed.

We invite you to read the dedicated documentation for a more detailed explanation of the Totals use case.

HTTP/1.0 422 Unprocessable Entity
{
   "error":{
      "message":"Il totale dei pagamenti non corrisponde al totale da pagare.",
      "validation_result":null
   },
   "extra":{
      "totals":{
         "amount_net":160.12,
         "amount_global_cassa_taxable":160.12,
         "taxable_amount":160.12,
         "vat_list":{
            "4":{
               "amount_net":151.92,
               "amount_vat":6.08
            },
            "22":{
               "amount_net":8.2,
               "amount_vat":1.8
            }
         },
         "amount_vat":7.88,
         "amount_gross":168,
         "amount_enasarco_taxable":0,
         "amount_due":168,
         "amount_due_discount":null,
         "payments_sum":100
      }
   }
}

🔁  Retry Strategy​

The temporary errors, such as the Rate or Usage limits errors and possibly the 5xx errors, can usually be solved simply by retrying after an interval that depends on the kind of error.

For the Limits and Quotas errors, the interval you must wait before sending a new request is known, so we return the Retry-After header to communicate exactly the amount of time you must wait to solve the issue.

If you want to try to avoid other unexpected temporary errors, we suggest adopting an exponential backoff strategy that uses an incremental interval strategy to try overcoming the error. You should use this strategy on every API method, checking the errors as explained above to stop the retries when the error is permanent (such as a validation error).

In this guide, you will find some code examples implementing this strategy.

📚  Additional Resources​