Errors and other HTTP response codes

Overview

Conventional HTTP response codes are used to indicate the success or failure of an API request.

Responses are grouped in five classes:

Informational responses (100-199)
Successful responses (200-299)
Redirection messages (300-399)
Client error responses (400-499)
Server error responses (500-599)

When an error occurs, DigiTax returns a structured JSON payload conforming to the following model:

{
  "code": "400",
  "message": "Invalid customer Tax Identification Number",
  "metadata": {
    "field": "identification_number"
  }
}

code: Machine-readable error code or HTTP status string.
message: Human-readable explanation of why the request failed.
metadata: Optional key-value object containing contextual diagnostic details (e.g. invalid field names).

For our interactive API, these are the main HTTP response status codes:

📘
503 is unlikely for DigiTax
We pride ourselves to provide 99.99% uptime!

Head over to the MDN reference on HTTP Status codes for details on the complete list of HTTP response status codes.

HTTP status	Scenario in DigiTax API	Action
200 OK	Typical for successful GET endpoint requests	Use the API response as needed
201 Created	Typical for successful POST endpoint requests	Use the API response as needed

HTTP status	Scenario in DigiTax API	Further context and possible action
400 Bad Request	Typical for POST endpoint requests	Action: Update the request body, headers, and/or parameters and retry
401 Unauthorized	Typical for POST and GET endpoint requests	For example, if you use an invalid or deactivated API Key, you receive a 401 error: `{"code": "401", "message": "bad credentials"}` Action: Check your API Key or generate one under Integrations.
403 Forbidden	Typical for POST endpoint requests	The user or token is not permitted to perform this action.
404 Not Found	Possible in any endpoint	Action: Verify the entity ID and endpoint route
409 Conflict	Typical for POST endpoint requests	For example, `trader_invoice_number` must be unique across all invoices. Reusing an existing value causes a conflict. Action: Retry with a different, unique `trader_invoice_number`
412 Precondition Failed	Typical for POST endpoint requests	A required precondition has not been met. The accompanying message will advise. Action: Update the request body and retry
429 Too Many Requests	Possible in any endpoint	All endpoints are rate-limited. You have exceeded the quota. Action: Retry later at a slower cadence
5XX (500, 501, 502, 503 ...)	Possible in any endpoint	Action: Check whether our team has issued an advisory on service interruption. If so, retry once resolution is communicated. If not, retry once. If a retry still returns a 5XX error, reach out to our support team.