Errors - Wizzgift Developers

The envelope

Every error (except 429, noted below) uses one JSON shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  },
  "requestId": "req_8f3k2"
}

Switch on error.code, never on message text — messages can change.
error.details carries structured context and is included in non-production environments.
Log requestId — include it when contacting support and we can trace the exact request.

Error codes

HTTP	Code	Meaning	Handling
400	`VALIDATION_ERROR`	Bad input; also synchronous payment failures (see `details.reason`, for example insufficient balance)	Fix the request; for balance failures, top up and retry
401	`UNAUTHORIZED`	Missing, invalid, or expired API key	Check the `X-API-Key` header and key status
403	`FORBIDDEN`	Missing key scope, capability disabled, or account suspended	Read the message hint; adjust key scopes or enable the capability
404	`NOT_FOUND`	Unknown id — also returned for resources owned by another account	Verify the id; do not retry
409	`CONFLICT`	`externalRef` used on the other surface, or a concurrent payment race	Cross-surface ref: fix the integration. Payment race: retry after a short delay
422	`B2B_LIMIT_EXCEEDED`	Tier limit hit — `details` identifies which	See limits and tiers
422	`PAYMENT_ERROR`	Payment-level failure	Inspect `details`; retry with a different method if appropriate
422	`INSUFFICIENT_BALANCE`	Balance too low for the operation	Top up via deposits
429	—	Rate limited	Exponential backoff
502	`EXTERNAL_SERVICE_ERROR`	Upstream provider failure	Safe to retry with backoff

The 429 response uses a flat body — { "error": "Too many requests", "message": "..." } — rather than the envelope. Match on the status code.

Ownership returns 404, not 403

Fetching a checkout, order, deposit, or refund that belongs to another account returns 404 NOT_FOUND — identical to a nonexistent id. This is deliberate: foreign ids do not leak existence. If you see unexpected 404s, verify you are querying the right surface (/b2b orders are invisible to /retailer/v1 endpoints and vice versa).

Retry classification

Class	Retry?
`429`, `502`, network timeouts	Yes, with exponential backoff — and the same `externalRef` on creates
`409` concurrent payment race	Yes, after a short delay
`400`, `401`, `403`, `404`, `422`	No — fix the underlying cause first