Common Errors

Authentication and Authorization Issues (401)

These errors are commonly referred to as 401 errors in the system and can be due to the following:

• Missing or Invalid Tokens: Ensure that valid API keys or tokens are included in each request.
• Expired access tokens: Check if your token has expired and refresh when necessary.
• Revoked access tokens: Admins can revoke access tokens for security and abuse-related cases. Users can also revoke access tokens on the eezi application.
• Incorrect Scopes or Permissions: eezi utilizes fine-grained scope access control to prevent unauthorized access or modification of data.

{ 
  "message":"Unauthorized"
}

{
  "error": {
    "message": "Unauthorized",
    "description": "Missing the following required scope to access this resource: invoice:read",
    "status": 401
  }
}

Rate Limit Exceeded (429 Too Many Requests)

Rate limits act as an additional level of protection for downstream partners and receiving parties.

{
  "message":"Too Many Requests"
}

Invalid parameters

Incorrect data will cause schema validation, logic validation, or downstream routing errors. As per the example below, errors will be indicated by an error key.

{
  "ref":"DCINV0XB8KWMPQVA68YT",
  // ...invoice fields without a total
  "error":{
    "name":"VALIDATION_SCHEMA",
    "status":400,
    "message":"Invalid invoice",
    "description":"\"total\" is required"
  }
}

{
  "ref":"DCINVITA0YSKJ22D5TSL",
  // ...invoice fields with invalid total
  "error":{
    "name":"VALIDATION_LOGIC",
    "status":400,
    "message":"Invalid invoice",
    "description":"Invoice total does not match line items."
  }
}

{
  "ref":"E2E-7c594bf4-e512-4dea-936d-e8c2b93947df",
  // ...invoice fields
  "error":{
    "name":"TAX_AUTHORITY_INVOICE_CREATE",
    "status":400,
    "message":"Invoice rejected",
    "description":"The document date is less than the last generated document date for the series name. Document date specified 2024-03-29 00:00:00, last document date: 2024-03-31 00:00:00, series name: SPINV15."
  }
}

Timeouts and Slow Responses

Various systems are involved to and from the receiving party when submitting invoices and other documents. In some cases, parallel routing and distribution post submission for mandated regions. To timeouts and slow responses, we implemented the following mitigating steps:

• Artificial and enforced timeouts: eezi automatically enforces timeouts after 29 seconds and responds with a timeout error
• 202 Accepted responses: For known long-running tasks or notoriously slow downstream systems, eezi will return 202 responses after applying its best effort to try and finalize a response.
• Read endpoints: The invoice and credit not read endpoints can be used to get the latest state of the document. We recommend calling the read endpoint in 30-second intervals to prevent overwhelming downstream systems and partners.

Test environments and simulated error responses

All eezi mock and test environments feature simulated error responses to several distinct error types for reliable testing of both positive and negative scenarios. Some are triggered by invalid data (schema or logic), and others can be forced by setting the total amount to specific values.

Success and Accepted - 2xx responses

Both VALIDATION_SCHEMA and VALIDATION_LOGIC share the same HTTP status of 400.

Schema or Logic validation - 400 Errors

Both VALIDATION_SCHEMA and VALIDATION_LOGIC share the same HTTP status of 400.

Miscellaneous - 403 Errors

Several different error scenarios fall under HTTP 403. Some can be forced in Test by setting the total to specific values (403.xx, 403.01).

Not found - 404 Errors

Rate limiting or Throttling - 429 Errors

Downstream - 503 Errors

These errors indicate downstream or external integration issues (e.g., with tax authorities). You can simulate many of these by setting total to specific values (503.xx, 1202.xx) or by meeting timing conditions (request older than 10 seconds).

Quick Reference Table: Forced Errors by total Value

Use the table below to see which errors can be intentionally forced in the Test environment by setting the total amount.

Notes:

• For the 202.xx and 1202.xx triggers, you must also ensure the request is over 10 seconds old to see the final status and message when fetching the document.