Errors

Every error uses the same three keys:

{
  "statusCode": 400,
  "error": "Error",
  "message": "dateFrom parameter is required (format: YYYY-MM-DD)"
}

statusCode repeats the HTTP status.
error is a short label: Internal Server Error for 500, Too Many Requests for 429, and Error for everything else.
message explains what went wrong.

There is no machine-readable error code. Branch on the HTTP status; use message for logs and for showing your team what happened.

On 500, message is a fixed generic apology. The real cause is logged on Zenamu’s side, so quote the timestamp and the endpoint when you contact support.

Handling errors

Treat 400, 401, 403, and 404 as client-correctable. Retrying an unchanged request will fail the same way — fix the request, the key, or the plan first. Treat 429 and 500 as transient. Back off and retry, but only where repeating the call is safe.

A 500 on a credit or pass grant is not safely repeatable on its own. The grant runs in a transaction, but the response never confirmed the outcome. Re-read the client’s balance with GET /v1/clients before granting again, or you may double-credit them.

Partial success

The bulk endpoints process each item independently, in order. One failing item does not roll back the rest, so the batch answers 200 even when items failed. Each clientId may appear only once in a batch, which keeps result-to-request mapping unambiguous:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "results": [
      { "clientId": 123, "success": true, "numberOfCredits": 510, "validTo": "2026-10-01" },
      { "clientId": 456, "success": false, "error": { "message": "Client not found" } }
    ],
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1,
      "failedClientIds": [456]
    }
  }
}

Never read a bulk 200 as “everything worked”. Check summary.failed, then map each result back to the request at the same array index. Inspect results[].error.message, correct permanent errors, and retry only selected failed items when the cause was fixed or transient. Do not retry the successful items.

Zenamu API

Objects

Endpoints

Handling errors

Partial success

​Handling errors

​Partial success

Handling errors

Partial success