Scheduled maintenanceScheduled maintenance: PayWise infrastructure maintenance is planned from Friday, October 9 at 7:00 p.m. ET through Monday, October 12 at 8:00 a.m. ET. Sandbox and Production services may experience intermittent interruptions during this period. Existing PayWise service URLs and SFTP hostnames will remain unchanged.
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.
  • Send PW-request-id on requests and propagate it across your own services.
  • Record PayWise request_id values returned in error payloads for support correlation.
  • Separate transient failures from terminal validation failures.