Skip to main content

Errors

Errors​

PayWise APIs return a consistent envelope to simplify parser and retry logic.

Standard envelope​

{
  "status": "error",
  "code": 400,
  "message": "Validation failed",
  "request_id": "req_01HXYZABC123",
  "timestamp": "2026-02-11T00:00:00.000Z",
  "errors": {
    "field": ["Must be a valid value"]
  }
}

Retry model​

  • 4xx: fix request before retry.
  • 409: resolve conflict or wait for state transition.
  • 429: honor Retry-After and apply backoff+jitter.
  • 5xx: safe retry with idempotency key.

Operational guidance​

  • Record upstream response bodies for non-2xx.
  • Capture and propagate request IDs across services.
  • Separate transient failures from terminal validation failures.