Errors and conventions

This page covers what is common to every endpoint: request conventions, status codes, the exact JSON shapes the API answers with, and what to do on each. The endpoint guides link here instead of repeating the shapes.

Conventions

HTTP status codes

Response body shapes

Validation error

400, returned when a required field is missing or a value is malformed. fieldErrors maps each offending field path to its problems. Nested paths use dots and array indexes are numbers: deviceData.device.ip, lineItems.0.name.

{
  "statusCode": 400,
  "message": "Some fields are invalid, please check the errors",
  "fieldErrors": {
    "amount": ["amount must not be less than 1", "amount must be an integer number"],
    "cardNumber": ["cardNumber must be 12-19 digits with no spaces or separators"]
  }
}

A validation error is stored under the Idempotency-Key like any other 4xx: fix the body and send it under a new key, otherwise the corrected request answers 422.

Plain error

The default shape for everything that is neither a decline nor a validation failure: 401, 403, 404, business-rule 400s, malformed ids, idempotency 409/422 and 5xx.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment not found: 01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b"
}

message is human-readable. It is stable enough to log and to show to an operator, but branch on the status code and the route, not on the text. Messages you will meet:

Charge decline

400 from auth-and-capture, auth and charge-saved-method. The charge was well-formed and was refused: by your account limits, by fraud screening, or by the card's issuer. There is no statusCode in this body; the HTTP status carries it. The payment is recorded with status: DECLINED so it appears in your reporting, but a declined direct charge does not return its paymentId.

{
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444",
  "cardExpiration": "1133",
  "cardholderName": "Jordan Example",
  "status": "DECLINED",
  "declinedReason": "Card declined"
}

charge-saved-method also uses this shape, without card fields, for an unknown payment method (404 with declinedReason: "Payment method not found.") and for ownership problems (400), see Saved payment methods.

Refund decline

400 from refund when the processor refused the refund or your daily refund limit blocked it. status is the refund's status, not the payment's.

{
  "paymentId": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "amount": 500,
  "cardNumber": "555555xxxxxxxx4444",
  "status": "FAILED",
  "declinedReason": "Amount exceeds daily refund limit"
}

cardNumber is null for wallet payments, which carry no card number. status is CANCELED only in the rare case where the refund was already cancelled on the processor's side before the call finished; no money moved either way.

Void and capture decline

400 from void and capture when the processor refused the operation. Here status: "DECLINED" describes the attempt, not the payment: read the payment to see where it stands.

{
  "paymentId": "01929a10-5d2e-7f3b-8c4d-1e2f3a4b5c6d",
  "amount": 7200,
  "cardNumber": "555555xxxxxxxx4444",
  "status": "DECLINED",
  "declinedReason": "Capture declined"
}

Reason-coded conflict

409 with a machine-readable reason. The rule fired before anything was charged or recorded, and the refusal is not stored under the Idempotency-Key, so the same key can be sent again once the condition clears.

{
  "statusCode": 409,
  "message": "This saved payment method has reached its reuse limit.",
  "reason": "REUSE_LIMIT"
}

A 409 without reason is a plain error: an Idempotency-Key still in flight, or a hosted checkout link that cannot be reissued.

Code-carrying errors

These errors carry a stable code.

HW_UNSUPPORTED (400): the hosted checkout is not enabled for your account. Nothing is written.

{
  "statusCode": 400,
  "error": "Bad Request",
  "code": "HW_UNSUPPORTED",
  "message": "Hosted checkout is not enabled for this account"
}

HW_NO_ACTIVE_PROVIDER_ACCOUNT (409): no account of yours takes new payments. On a payment that already exists, HW_PROVIDER_ACCOUNT_REFUND_ONLY, HW_PROVIDER_ACCOUNT_RESTRICTED, HW_PROVIDER_ACCOUNT_DISABLED or HW_PROVIDER_ACCOUNT_UNRESOLVED (409): the account it was created on no longer takes payments. Neither is stored under an Idempotency-Key, so the same key can be retried once High Wire has resolved the account.

{
  "statusCode": 409,
  "error": "Conflict",
  "code": "HW_NO_ACTIVE_PROVIDER_ACCOUNT",
  "message": "No active provider account can take this payment."
}

VELOCITY_LIMIT (429): a velocity check refused a card charge. Nothing is charged and no payment is recorded. There is no Retry-After header. See Account limits.

{
  "statusCode": 429,
  "message": "Velocity limit exceeded",
  "code": "VELOCITY_LIMIT"
}

Server errors

A 5xx is a plain error. The idempotency record for the call is discarded, so retry with the same Idempotency-Key; a retry under the same key cannot charge twice. A retry can answer a plain 400 such as This payment has already been captured. when the first attempt did go through; read the payment to confirm.

A 500 whose message says the operation was accepted (Capture accepted; finalization pending. Poll the payment., and the same for a void or a refund) means exactly that: do not retry; poll the payment until it reflects the operation.

Telling the shapes apart

Check the body in this order; the first match wins.

1. fieldErrors present: a validation error.
2. declinedReason present: a decline. status says which kind: DECLINED for a charge, void or capture; FAILED or CANCELED for a refund.
3. reason present: a reason-coded conflict.
4. code present: a code-carrying error.
5. Otherwise a plain error; use statusCode.

Retrying