Errors

Every error has the same shape: an error object with a machine-readable code and a human-readable message. Some errors add fields, such as errors for validation problems or transaction for declines.

{
  "error": {
    "code": "invalid_request",
    "message": "The amount field is required.",
    "errors": {
      "amount": ["The amount field is required."]
    }
  }
}

Branch on code, not on message: messages can be reworded.

HTTP statuses

Declines and gateway failures

A charge, capture, void or refund that reached the gateway but was not approved answers 402. The error carries the recorded transaction, so you can show the reason and keep its id:

{
  "error": {
    "code": "card_declined",
    "message": "The card has insufficient funds.",
    "decline_code": "insufficient_funds",
    "transaction": { "object": "transaction", "id": "txn_01jaxs6q9s2u5w8y1a4c7e0g3j", "status": "declined" }
  }
}

code is one of:

See Declines for every decline_code and the AVS and CVV results.

Other codes