Errors

Each error uses the same wrapper. The wrapper has a stable code and a message for a person to read. Use the code to select the action in your integration. The text of the message can change.

{ "error": { "code": "insufficient_funds", "message": "..." } }

Jenzy publishes these codes. Jenzy never renames a code and never removes a code. Jenzy only adds codes. Use the code field. Do not use the message field or the HTTP reason text.

Two groups of codes

There are two groups of errors. The two groups do different things with your money.

Rejections (the first table) — Hermes refused the request. Hermes created no payout and held no money. Correct the request, or wait, and then send the request again.
Failure codes (the second table) — Hermes accepted the payout, held the funds, and the payout failed later. The payout is terminal, and Hermes sets failure: { code, message }. Hermes always releases the hold back to your available balance. To try again, always create a new payout with a new Idempotency-Key.

Rejection codes

Code	HTTP	Meaning	Send again?
`validation_error`	400	The request has an error: bad JSON, an absent field, or no `Idempotency-Key` on a create.	Yes, after you correct the request.
`unauthorized`	401	The API key is absent, malformed, revoked, or unknown.	No. Correct the key.
`forbidden`	403	Jenzy suspended your org, or your allowlist does not have the request IP.	No. Speak to Jenzy, or correct the allowlist.
`not_found`	404	Your org has no such resource. An unknown id, an id of a different org, and a malformed id all look the same.	No.
`insufficient_funds`	402	The amount is more than your available balance.	Yes, after you fund the balance. Send money to your account number.
`conflict`	409	You used this `Idempotency-Key` with a different body, or the first request is still in progress.	For a different body, use a new key. For a request in progress, use the same key after a short time.
`unknown_institution`	422	The rail of this endpoint cannot pay the `institution_id`. The message tells you if the id is unknown or on the other rail.	Yes, after you read `GET /institutions` again, or after you call the endpoint of the other rail.
`invalid_mobile_number`	422	The mobile number is not 12 digits in the full international form. Use `265`, then `9` for Airtel Money or `8` for TNM Mpamba, then 8 digits. An example is `265991234567`. Hermes never corrects a number for you.	Yes, after you correct the number.
`mobile_number_institution_mismatch`	422	The network of the number is not the institution that you chose. Examples are a `2659…` number sent to TNM Mpamba, and a `2658…` number sent to Airtel Money. That payout can go to the wrong destination. The message names the correct institution.	Yes, after you choose the institution that agrees. The number is correct.
`invalid_account_number`	422	The account number is not valid for the destination bank.	Yes, after you correct the number.
`amount_limit_exceeded`	422	This payout is above the per-payout maximum.	Yes, with a smaller amount.
`rate_limited`	429	You sent too many requests.	Yes. Obey the `Retry-After` header.
`org_limit_exceeded`	429	Your org went above its daily cap or its payout velocity limit.	Yes, later.
`internal_error`	500	Hermes has an internal problem.	Yes. On a create, use the same `Idempotency-Key`. You get the first result, and never two payouts.
`rail_disabled`	503	An administrator paused this rail.	Yes, later.
`service_unavailable`	503	A dependency is not available. For example, the reference data did not sync one time.	Yes, later.
`service_incident`	503	Jenzy paused the full `/v1` API to examine a problem. Your balance is safe. Each payout that Hermes accepted is safe. Hermes retries nothing.	Yes, later. On a create, you can use the same `Idempotency-Key`. A pause never uses a key.
`service_maintenance`	503	Jenzy paused the full `/v1` API for planned work.	Yes, later, with the same key.

Failure codes

A failed payout has one of these codes in failure.code. The code is the same on GET /payouts/{id} and in the payout.failed webhook. The failure.message text does not change for a given code. You can show that text to your own users.

Code	Meaning	Can a second payout succeed?
`recipient_account_invalid`	The provider refused the destination. The account does not resolve, or the number is not valid.	Only after you correct the destination.
`declined`	The provider declined the payout, or failed it with no reason. Hermes uses this code when no other code applies.	Not usually. Examine the payout before you send it again.
`provider_unavailable`	The downstream provider had a timeout or an outage.	Yes. Send a new payout after a short time.
`temporarily_unavailable`	Hermes had a temporary condition.	Yes. Send a new payout later. Hermes took no funds.

When Jenzy pauses the API

See Maintenance and outages for the procedure that your system must obey. service_incident and service_maintenance are the only two codes that mean Jenzy stopped this on purpose. They are different from each other rejection in one way: they do not use your Idempotency-Key. Each other decided result, a new payout or a 4xx, is final for that key. A pause is not a decision. So the safe action is the same key with the same body. You then get a payout, and not a conflict. While one of the two codes applies:

Each /v1 route, but not GET /ping, gives 503. This includes the read endpoints, POST /fees/quote, the payout creates, and POST /collections/simulate.
GET /ping continues to answer. Its status field is outage for an incident, or maintenance for planned work.
Payouts that Hermes accepted before the pause stay in held. Hermes did not send them. They did not fail. No money moved for them. They continue automatically when the pause ends.
Hermes still delivers the webhooks for payouts that already got a result.

Jenzy does not send a Retry-After header with these codes. A person at Jenzy decides when a pause ends. So a timestamp from Jenzy would only be a guess.

Hermes never sends a failed payout again. The four codes above are the complete set of failure codes. Hermes uses declined for each failure that does not agree with the other three codes.

Get started

Guides

Two groups of codes

Rejection codes

Failure codes

When Jenzy pauses the API

​Two groups of codes

​Rejection codes

​Failure codes

​When Jenzy pauses the API

Two groups of codes

Rejection codes

Failure codes

When Jenzy pauses the API