Errors and other HTTP response codes

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 terms
  • code: the HTTP status code, as a string
  • metadata: 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_number or 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 CodeScenario in DigiTax APIAction
200 OKTypical for successful GET and PUT requestsUse the API response data as needed
201 CreatedTypical for successful POST requests. Also returned when you retry a receipt with the same trader_invoice_number, with the receipt already issuedUse the response. For a receipt, follow its status until ZIMRA has it

Client Error Responses

HTTP Status CodeScenario in DigiTax APIContext & Action
400 Bad RequestRequest or receipt validation failedExamples: 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 UnauthorizedMissing, expired, or invalid API KeyReturned when the X-API-Key header is missing or the key is inactive.
Action: Verify your API Key from the DigiTax dashboard.
403 ForbiddenInsufficient permissionsThe API Key doesn't have rights to this business or resource.
404 Not FoundResource or route not foundExamples: 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 ConflictDuplicateExamples: 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 FailedDevice or fiscal day stateExamples: 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 RequestsRate limit quota reachedAction: Back off and retry requests with exponential backoff.
5XX Server ErrorsService interruption or upstream errorAction: 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.