HTTP response codes for troubleshooting: invalid data, duplicates, device and fiscal day states, and more.
Overview
Conventional HTTP response codes indicate the success or failure of an API request.
Responses are grouped into standard classes:
- Successful responses (200 – 299)
- Redirection messages (300 – 399)
- Client error responses (400 – 499)
- Server error responses (500 – 599)
Standard Error Response Body
When an error occurs, the DigiTax Zimbabwe API returns a JSON error envelope:
message: what went wrong, in general termscode: the HTTP status code, as a stringmetadata: details as string key-value pairs, such as the field or the ID concerned. Left out when there are none
A receipt whose total doesn't match its lines looks like this:
{
"message": "total_cents must equal the total computed from the lines and their taxes",
"code": "400",
"metadata": {
"argument": "total_cents",
"expected_cents": "310",
"computed_cents": "300",
"count": "1",
"codes": "RCPT019",
"fields": "total_cents",
"violations": "[{\"code\":\"RCPT019\",\"colour\":\"Red\",\"field\":\"total_cents\",\"message\":\"total_cents must equal the total computed from the lines and their taxes\",\"meta\":{\"computed_cents\":\"300\",\"expected_cents\":\"310\"}}]"
}
}When a receipt breaks several rules, message only summarises them, and the details are in metadata. Read metadata.codes (comma-separated rule codes) and metadata.violations, a JSON array encoded as a string with one {code, colour, field, message, line_no, meta} object per broken rule. See Checks before a receipt is issued.
DigiTax API HTTP Response Status Codes
For the interactive DigiTax Zimbabwe API, these are the primary HTTP response codes:
- 200 OK: Request succeeded.
- 201 Created: Resource created successfully.
- 400 Bad Request: Request validation failed.
- 401 Unauthorized: Authentication failed (missing or invalid
X-API-Key). - 403 Forbidden: The API key isn't allowed this operation.
- 404 Not Found: Resource or endpoint path not found.
- 409 Conflict: A duplicate, such as a reused
trader_invoice_numberor barcode. - 412 Precondition Failed: Your device or fiscal day isn't in a state that allows the request yet.
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Internal server issue.
Further Context and Action Points
Successful Responses
| HTTP Status Code | Scenario in DigiTax API | Action |
|---|---|---|
| 200 OK | Typical for successful GET and PUT requests | Use the API response data as needed |
| 201 Created | Typical for successful POST requests. Also returned when you retry a receipt with the same trader_invoice_number, with the receipt already issued | Use the response. For a receipt, follow its status until ZIMRA has it |
Client Error Responses
| HTTP Status Code | Scenario in DigiTax API | Context & Action |
|---|---|---|
| 400 Bad Request | Request or receipt validation failed | Examples: a receipt that breaks a rule (metadata.codes, metadata.violations); both before and after sent; a time filter without an offset; a trader_invoice_number in the form of a DigiTax-generated invoice number.Action: Fix the request and retry. |
| 401 Unauthorized | Missing, expired, or invalid API Key | Returned when the X-API-Key header is missing or the key is inactive.Action: Verify your API Key from the DigiTax dashboard. |
| 403 Forbidden | Insufficient permissions | The API Key doesn't have rights to this business or resource. |
| 404 Not Found | Resource or route not found | Examples: an unknown ID, or a credit note's original_receipt_id that isn't one of yours.Action: Check the URL path and IDs. |
| 409 Conflict | Duplicate | Examples: the same trader_invoice_number with a different sale; a trader_invoice_number already sent to ZIMRA for another receipt on the device; an item with a barcode already in use; on POST /detailed-receipts, an inline item or customer that already exists with a different definition (metadata.item_id or metadata.customer_id, and metadata.fields).Action: Use a unique value, or refer to the existing item or customer. |
| 412 Precondition Failed | Device or fiscal day state | Examples: the device isn't registered with ZIMRA, isn't ACTIVE or has no valid certificate yet (check GET /fdms-info); DigiTax is closing the fiscal day, which usually takes a few seconds; a fiscal day report requested while the day is still opening; a credit note whose original isn't a fiscal invoice or is on another device.Action: For a closing fiscal day, retry with the same trader_invoice_number. Otherwise fix the state first. |
| 429 Too Many Requests | Rate limit quota reached | Action: Back off and retry requests with exponential backoff. |
| 5XX Server Errors | Service interruption or upstream error | Action: Retry later, or reach out to [email protected]. Retrying a receipt with the same trader_invoice_number never issues it twice. |
Errors after a receipt is issued
A 201 means DigiTax has issued and signed the receipt, not that ZIMRA has accepted it. ZIMRA's verdict comes later, on the receipt's status, validation_colour and validation_errors, and through the zimra.receipt.flagged callback. See Receipt statuses and validation.