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)

DigiTax API HTTP response status codes

For our interactive API, these are the main HTTP response status codes (Client error responses and Server error responses included):

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
412 Precondition Failed
429 Too Many Requests
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable

📘
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 entire list of HTTP response status codes.

Further context and Possible action points

Successful responses

HTTP response status codes	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

Client error responses

HTTP response status codes	Scenario in DigiTax API	Further context and Possible action points
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 a wrong/ deactivated API Key, you get a 401 error with the response body as: `{"message": "bad credentials"}` Action: Check API Key or add one if you hadn't already. The message returned will advise otherwise.
403 Forbidden	Typical for POST endpoint requests	The user who generated the API Key is not allowed to perform the action or view the resource.
404 Not Found	Possible in any endpoint	Action: Update the endpoint path or route
409 Conflict	Typical for POST endpoint requests	For example, `trader_invoice_number` should be unique across all sales/ credit notes and debit notes. If you repeat the value of an existing invoice in a POST request, the request will fail with this error. Action: Retry with a different, unique `trader_invoice_number`
412 Precondition Failed	Typical for POST endpoint requests	There are several actions that need Preconditions met. The message accompanying the error will advise. Below are examples. (For Credit Notes) `credit note can only be created for signed invoices` `item amount more than amount in original invoice` (For Invoices) `items sent are more than those found, check that you haven't duplicated an item` - Which means that you have likely duplicated an item in the request. (For Items) `tax category not found` Action: Update the request body and retry
429 Too Many Requests	Possible in any endpoint	Since all endpoints are rate-limited, you have reached the set user quota/ rate limit. Action: Retry later at a slower cadence
5XX (501, 502, 503, 504 ...)	Possible in any endpoint	Action: Confirm that our team has issued an advisory on service interruption. If so, retry once a resolution of the issue has been communicated. If not, please retry. If a retry still returns a 5XX error, kindly reach out to our support team.