Codes and Formats

This page describes the conventions shared by every enza API endpoint: the HTTP status codes we return, the shape of success and error responses, the error-code catalogue, and the formats used for common field types.

---

HTTP response codes

Status	Meaning	Description
200	OK	The request succeeded and the response body contains the result.
201	CREATED	A resource was created. The body contains the new resource plus a meta block.
400	BAD REQUEST	The request is malformed — invalid JSON, a missing/invalid field, or an invalid Idempotency-Key.
401	UNAUTHORIZED	The x-api-key header is missing.
403	FORBIDDEN	The x-api-key is invalid or revoked, or the key is not permitted to use this route, source IP, or resource.
404	NOT FOUND	The requested resource (customer, card, account, …) does not exist — or the route/method is not recognised.
405	METHOD NOT ALLOWED	The HTTP method is not supported for this resource. (An unknown route or verb usually surfaces as 404.)
409	CONFLICT	Conflicts with the current state — a duplicate, an "already exists", or an Idempotency-Key reused/in progress.
413	PAYLOAD TOO LARGE	The request body exceeds the maximum allowed size.
415	UNSUPPORTED MEDIA TYPE	The Content-Type is missing or not application/json.
422	UNPROCESSABLE CONTENT	The request is well-formed but fails business validation (declined, not eligible, insufficient funds).
429	TOO MANY REQUESTS	Rate limit or quota exceeded. Retry after a short delay.
500	INTERNAL SERVER ERROR	An unexpected error occurred on our side (ERR_INTERNAL_SERVER_ERROR), including an unrecognised upstream fault.
502	BAD GATEWAY	An upstream system returned an invalid response (ERR_BAD_GATEWAY).
503	SERVICE UNAVAILABLE	An upstream system is unreachable / down (ERR_SERVICE_UNAVAILABLE). Safe to retry shortly with the same Idempotency-Key.
504	GATEWAY TIMEOUT	An upstream system timed out (ERR_TIMEOUT). Safe to retry with the same Idempotency-Key.

Auth note: a missing x-api-key returns 401; an invalid/revoked key, or one not permitted for the route/IP/resource, returns 403.

---

Success responses

Responses are unenveloped — the resource is returned at the top level, with a meta sidecar. There is no wrapper object around the payload.

A success response does not include a code field — use the HTTP status to determine the outcome (200 = OK, 201 = created). A success body may include a human-readable message; do not rely on its exact wording. Error responses always include a code — switch on that (see Error responses).

200 OK — a read or update:

Code
{
  "maskedPan": "537251******8472",
  "status": "Active",
  "expiryDate": "2027-12-31",
  "availableBalance": "1500.00",
  "currency": "840",
  "meta": {
    "timestamp": "2026-05-20T09:11:11.566Z"
  }
}

201 CREATED — a resource was created:

Code
{
  "message": "Customer created successfully",
  "customerId": "123456789",
  "meta": {
    "timestamp": "2026-05-20T09:11:11.566Z"
  }
}

The meta object

Field	Type	Description
timestamp	string	ISO 8601 date-time (UTC) when the request was processed.

meta is present once the request has been processed. Requests rejected earlier (e.g. 400 validation, 401 auth) do not carry a meta.

---

Error responses

Every error uses the same structure:

Code
{
  "code": "ERR_VALIDATION_FAILED",
  "message": "Validation failed",
  "details": [
    { "field": "email", "reason": "Invalid email format" }
  ],
  "meta": {
    "timestamp": "2026-05-20T09:11:11.566Z"
  }
}

Field	Type	Description
code	string	Machine-readable error code (see catalogue below). Switch on this, not on message.
message	string	Human-readable explanation. Wording may change; the code will not.
details	array	Optional. Per-field problems, present for validation errors. Each item has field and reason.
meta	object	Optional. Present once the request has been processed (see above).

Validation error (400) — note there is no meta (rejected before processing):

Code
{
  "code": "ERR_VALIDATION_FAILED",
  "message": "Validation failed",
  "details": [
    { "field": "requestType", "reason": "Required field missing" }
  ]
}

Conflict (409) — processed, so meta is present:

Code
{
  "code": "ERR_CUSTOMER_ALREADY_EXISTS",
  "message": "Customer already exists",
  "meta": {
    "timestamp": "2026-05-20T09:11:11.566Z"
  }
}

---

Error code catalogue

Codes are grouped by the HTTP status they return with. Each endpoint's reference lists the specific codes it can return; the common ones are:

400 — Bad Request (structure / format)

ERR_VALIDATION_FAILED · ERR_INVALID_JSON · ERR_BODY_EMPTY · ERR_MISSING_PARAM · ERR_MISSING_ACCOUNT_NUMBER · ERR_INVALID_ACCOUNT_NUMBER · ERR_INVALID_AMOUNT · ERR_INVALID_COUNTRY_CODE · ERR_INVALID_TIME_RANGE · ERR_IDEMPOTENCY_KEY_REQUIRED · ERR_IDEMPOTENCY_KEY_INVALID

401 / 403 — Authentication & authorization

ERR_AUTH_CONTEXT (401, missing key) · ERR_FORBIDDEN · ERR_UNAUTHORIZED · ERR_INVALID_API_KEY · ERR_INVALID_SIGNATURE · ERR_TOKEN_EXPIRED (all 403)

Note: a missing x-api-key is 401; an invalid/revoked key (and any route/IP/resource denial) is 403 — so ERR_UNAUTHORIZED is returned with HTTP 403.

404 — Not Found

ERR_CUSTOMER_NOT_FOUND · ERR_CARD_NOT_FOUND · ERR_ACCOUNT_NOT_FOUND · ERR_HOLD_NOT_FOUND · ERR_LINK_NOT_FOUND · ERR_COUNTRY_NOT_FOUND · ERR_CURRENCY_NOT_FOUND · ERR_LAST_ATC_NOT_FOUND · ERR_MAIN_CARD_NOT_FOUND · ERR_PIN_TRIALS_NOT_FOUND · ERR_RESTRICTION_NOT_FOUND · ERR_SOURCE_PAN_NOT_FOUND · ERR_DESTINATION_PAN_NOT_FOUND

405 — Method Not Allowed

ERR_METHOD_NOT_ALLOWED

409 — Conflict (duplicate / idempotency)

ERR_CUSTOMER_ALREADY_EXISTS · ERR_ACCOUNT_ALREADY_EXISTS · ERR_ACCOUNT_EXISTS · ERR_CARD_ALREADY_ASSIGNED · ERR_DUPLICATE_UUID · ERR_NOTIFICATION_SERVICE_EXISTS · ERR_IDEMPOTENCY_KEY_ALREADY_USED · ERR_IDEMPOTENCY_IN_PROGRESS

413 / 415 — Request not accepted

ERR_PAYLOAD_TOO_LARGE (413) · ERR_UNSUPPORTED_MEDIA_TYPE (415)

422 — Unprocessable (business validation)

ERR_CARD_DECLINED · ERR_CARD_CREATION_DECLINED · ERR_ACTIVATE_CARD_DECLINED · ERR_LINKING_DECLINED · ERR_PIN_CHANGE_DECLINED · ERR_PIN_SETTING_DECLINED · ERR_PIN_AUTH_FAILED · ERR_PAYMENT_FAILED · ERR_INSUFFICIENT_FUNDS · ERR_INSUFFICIENT_BALANCE · ERR_AMOUNT_EXCEEDS_HOLD · ERR_CURRENCY_MISMATCH · ERR_CARD_NOT_ACTIVE · ERR_CARD_INACTIVE · ERR_CARD_NOT_VALID · ERR_CARD_NOT_VIRTUAL · ERR_CARD_NOT_ELIGIBLE_FOR_REISSUE · ERR_CARD_NOT_ELIGIBLE_FOR_RENEWAL · ERR_CARD_NOT_ELIGIBLE_FOR_REPLACEMENT · ERR_CANNOT_REISSUE_VIRTUAL_CARD · ERR_CONTRACT_BLOCKED · ERR_CONTRACT_NOT_ACTIVE · ERR_CONTRACT_RESTRICTED · ERR_ACCOUNT_NOT_ACTIVE · ERR_SOURCE_CARD_INACTIVE · ERR_DESTINATION_CARD_INACTIVE · ERR_NO_ACCOUNT_LINKED · ERR_HOLD_ALREADY_CLOSED · ERR_HOLD_NOT_BELONG

429 — Rate limited

ERR_RATE_LIMITED

500 — Server error

ERR_INTERNAL_SERVER_ERROR · ERR_INTERNAL · ERR_CARD_REISSUE_FAILED · ERR_CARD_RENEWAL_FAILED · ERR_CARD_REPLACEMENT_FAILED · ERR_PIN_SET_FAILED

502 / 503 / 504 — Upstream unavailable

ERR_BAD_GATEWAY (502, invalid upstream response) · ERR_SERVICE_UNAVAILABLE (503, upstream unreachable / down) · ERR_TIMEOUT (504, upstream timed out)

503 and 504 are safe to retry shortly with the same Idempotency-Key.

Tip: integrate against the code field, not the HTTP status or the message text. Codes are stable; messages may be reworded.

---

Field formats

Type	Format	Example
Date	ISO 8601 date, YYYY-MM-DD	1990-01-01
Timestamp	ISO 8601 date-time, UTC	2026-05-20T09:11:11.566Z
Country code	ISO 3166-1 numeric	826 (United Kingdom)
Currency code	ISO 4217 numeric	840 (USD)
Amount	Decimal number or numeric string	1500.00
Email	RFC 5322 address	john.doe@example.com
Idempotency-Key	UUID v4	550e8400-e29b-41d4-a716-446655440000
PAN	13–19 digits; masked as 6 + * + last 4	537251******8472