Errors, Warnings and how to handle them

Stateless validations are performed synchronously (e.g., date format, currency, customer type, …) and the error response is returned immediately.

Additional validations are performed asynchronously (e.g., supplier reference, transaction reference check, tax authority errors) and are returned via webhooks.

Synchronous errors

Submitting an invalid payload will result in a 400 Bad Request with a list of errors explaining what exactly went wrong.

Here’s an example of an invalid payload for submitting a transaction:

POST https://api.fonoa.com/v1/transactions

{
  "country_code": "MX",
  "language_code": "ES",
  "currency_code": "USD",
  "transaction_date": "2022-08-02T12:51:25Z",
  "transaction_number": "__TEST_TRANSACTION_NUMBER__",
  "transaction_id": "FONOA_TEST_003",
  "items": [
    {
      "number": 1,
      "name": "Chocolate cookies",
      "quantity": 3.0,
      "unit": "pcs",
      "unit_price": 7570,
      "description": "Chocolate cookies taste better with milk",
      "tax_breakdowns": [
        {
          "rate": 25.0,
          "regime": "RET",
          "type": "ISR"
        }
      ]
    }
  ],
  "supplier": {
    "id": "a7cc64422fc247069aa64d4fe8b387c5"
  },
  "payments": [
    {
      "type": "OTHER",
      "code": "PPD",
      "amount": 7570
    }
  ],
  "tax_reason": "WHTVR"
}

The following response shall be returned:

400 Bad Request

{
	"errors": [
		{
			"code": "validation_match_invalid",
			"message": "Transaction currency must be MXN (Mexican Peso) when reporting MX transactions to the tax authorities.",
			"type": "validation"
		},
		{
			"code": "field_not_valid",
			"message": "Sum of payment amounts (7570) must be equal to total transaction amount (22710).",
			"type": "validation"
		},
		{
			"code": "field_not_valid",
			"message": "tax_reason must be one of the following: G01, G02, G03, I01, I02, I03, I04, I05, I06, I07, I08, D01, D02, D03, D04, D05, D06, D07, D08, D09, D10, S01, CP01, CN01.",
			"type": "validation"
		},
		{
			"code": "unsupported_field",
			"message": "Transaction number is not supported when reporting MX transactions to the tax authorities.",
			"type": "validation"
		}
	],
	"message": "Invalid transaction payload"
}

Handling synchronous errors

Fonoa does not store the Transactions that fail with synchronous client errors.

Clients should fix their transaction payload and resubmit the transaction with the correct payload.

Fonoa will track the client error rate and proactively inform the client in case anomalies are noticed.

Asynchronous errors

Some errors can only surface after the transaction is submitted. In such cases, Fonoa will notify the client using the same webhook mechanism described in the above section.

If there are issues with processing the transaction, the transaction payload will contain a list of errors. Here’s an example of a transaction with asynchronous error:

GET https://api.fonoa.com/v1/transactions/bdde0576-a947-11ed-8347-32dd94c2de80

200 OK
 
{
  ... // removed full payload for brevity
  "status": "FAILURE",
  "errors": [
    {
       "code": "internal_server_error",
      "message": "An internal error has occurred. Please contact Fonoa with the TransactionId for details.",
	 "type": "GENERAL"
    }
  ],
  "transaction_id": "TEST_TRANSACTION_MX_ID_0026"
}

Handling asynchronous errors

Transactions that fail with an asynchronous error are stored in the Fonoa system. They are considered unsuccessfully processed.

Error handling depends on the type:

• Validation errors (e.g., invalid supplier, invalid reference, etc.)
  Clients should fix the issue and replay the transaction
• Tax authority errors (caused by TA downtime, TA bugs, additional validations not covered by Fonoa)
  Clients should replay the transaction
  If the issue persists, reach out to Fonoa for help
• Internal server errors (e.g., a bug in Fonoa system)
  Fonoa team has been informed about the issue
  Once the issue is resolved, Fonoa will re-process the transaction and inform the client about the result via webhooks

Warnings

Sometimes a transaction could be reported successfully but the tax authority returns one or more warnings related to the payload. Clients will need to review the warning and take any potential action. A warning could be related to system improvements or data issues. Data issues should be solved through an adjustment given the transaction was accepted.

An example result is shown below. The result is a success, but we pass along the tax_authority_warning which needs to be reviewed - and potentially addressed for next time.

{  
  ...  // removed full payload for brevity
  "reported_at": "2023-01-23T11:47:37.774343841Z",  
  "status": "SUCCESS",
  ...
  "errors": [  
     {  
       "code": "tax_authority_warning",  
     "message": "Business validation message: Incorrect customer tax number. If KBAET is chosen, only the community tax number can be filled in."  
    }  
  ]  
  ...  
}