> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paychoice.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes, the two error body formats, and gateway error codes.

## HTTP status codes

Check the HTTP status first. Anything other than `200 OK` (or `201 Created` on v5 token creation) indicates an error; the body carries the detail.

| HTTP code | Meaning |
| - | - |
| `200 OK` | Request succeeded |
| `201 Created` | v5 only: a token was created |
| `400 Bad Request` | Missing or malformed parameter |
| `401 Unauthorized` | Credentials missing or invalid. Payment endpoints return an empty body |
| `402 Payment Required` | The charge was not approved; read `charge.status`, `error` and `error_code` |
| `403 Forbidden` | Billing: the credential can't access this merchant or customer, or the action isn't permitted (e.g. attaching a bank account already attached elsewhere) |
| `404 Not Found` | The record doesn't exist or isn't visible to this credential |
| `409 Conflict` | The charge reference was already in use; or a dishonour fee can't be charged in its current state |
| `410 Gone` | The resource no longer exists, e.g. a removed card or bank token |
| `422 Unprocessable Entity` | Billing: validation failed, or the record isn't in a state that allows the action |
| `500 Internal Server Error` | An error occurred on the PayChoice server |
| `504 Gateway Timeout` | A transaction took longer than expected to process |

## Error body — payments (charges, tokens, refunds, webhooks)

```json theme={null}
{
  "error": {
    "message": "Error message here",
    "param": "400"
  },
  "object_type": "error",
  "from_item": 0,
  "to_item": 0,
  "total_count": 0
}
```

`error.param` is usually the HTTP status as a string; occasionally a status name such as `"BadRequest"`. A declined charge (`402`) returns the normal `charge` envelope rather than this object.

## Error body — Billing

Send `Accept: application/json` on every Billing request; without it, errors come back as HTML.

```json theme={null}
{
  "status": false,
  "code": 422,
  "messages": [
    { "message_text": "The email field is required.", "message_type": "error", "message_field": "email" }
  ],
  "message": "The given data was invalid."
}
```

`status` is `false`, `code` matches the HTTP status, `messages` has one item per problem (`message_field` on validation errors), and `message` is `Unauthorized`, `Forbidden`, `Not Found`, `The given data was invalid.` or the specific message for other errors.

## Gateway error codes

Returned in `error_code` on charges, refunds and pre-authorisations, and in webhook payloads.

> [accordion] Visa & Mastercard
>
> | Code | Description |
> | - | - |
> | 0 | Transaction Approved |
> | 1 | Refer to Issuer |
> | 2 | Refer to Issuer, special |
> | 3 | No Merchant |
> | 4 | Pick Up Card |
> | 5 | Do Not Honour |
> | 6 | Error |
> | 7 | Pick Up Card, Special |
> | 8 | Honour With Identification |
> | 9 | Request in Progress |
> | 10 | Approved for Partial Amount |
> | 11 | Approved, VIP |
> | 12 | Invalid Transaction |
> | 13 | Invalid Amount |
> | 14 | Invalid Card Number |
> | 15 | No Issuer |
> | 16 | Approved |
> | 19 | Re-enter Last Transaction |
> | 21 | No Action Taken |
> | 22 | Suspected Malfunction |
> | 23 | Unacceptable Transaction Fee |
> | 25 | Unable to Locate Record on File |
> | 30 | Format Error |
> | 31 | Bank Not Supported by Switch |
> | 33 | Expired Card, Capture |
> | 34 | Suspected Fraud, Retain Card |
> | 35 | Card Acceptor, Contact Acquirer, Retain Card |
> | 36 | Restricted Card, Retain Card |
> | 37 | Contact Acquirer Security Department, Retain Card |
> | 38 | PIN Tries Exceeded, Capture |
> | 39 | No Credit Account |
> | 40 | Function Not Supported |
> | 41 | Lost Card |
> | 42 | No Universal Account |
> | 43 | Stolen Card |
> | 44 | No Investment Account |
> | 51 | Insufficient Funds |
> | 52 | No Cheque Account |
> | 53 | No Savings Account |
> | 54 | Expired Card |
> | 55 | Incorrect PIN |
> | 56 | No Card Record |
> | 57 | Function Not Permitted to Cardholder |
> | 58 | Function Not Permitted to Terminal |
> | 59 | Suspected Fraud |
> | 60 | Acceptor Contact Acquirer |
> | 61 | Exceeds Withdrawal Limit |
> | 62 | Restricted Card |
> | 63 | Security Violation |
> | 64 | Original Amount Incorrect |
> | 66 | Acceptor Contact Acquirer, Security |
> | 67 | Capture Card |
> | 75 | PIN Tries Exceeded |
> | 82 | CVV Validation Error |
> | 90 | Cutoff in Progress |
> | 91 | Host or Switch Unavailable / Card Issuer Signed Off / Timed Out / Unavailable |
> | 92 | Unable to Route Transaction |
> | 93 | Cannot Complete, Violation of The Law |
> | 94 | Duplicate Transaction |
> | 96 | System Error |

> [accordion] American Express
>
> | Code | Description |
> | - | - |
> | 0 | Approved |
> | 1 | Approve with ID |
> | 2 | Partial Approval (Prepaid Cards only) |
> | 100 | Deny |
> | 101 | Expired Card / Invalid Expiration Date |
> | 106 | Exceeded PIN attempts |
> | 109 | Invalid merchant |
> | 110 | Invalid amount |
> | 111 | Invalid account / Invalid MICR (Travelers Cheque) |
> | 115 | Requested function not supported |
> | 116 | Not Sufficient Funds |
> | 117 | Invalid PIN |
> | 119 | Cardmember not enrolled / not permitted |
> | 121 | Limit Exceeded |
> | 122 | Invalid card security code (CID, 4DBC, 4CSC) |
> | 125 | Invalid effective date |
> | 130 | Additional customer identification required |
> | 181 | Format error |
> | 183 | Invalid currency code |
> | 187 | Deny - New card issued |
> | 189 | Deny - Canceled or Closed Merchant/SE |
> | 190 | National ID Mismatch |
> | 200 | Deny - Pick up card |
> | 900 | Accepted - ATC Synchronization |
> | 909 | System Malfunction (Cryptographic Error) |
> | 912 | Issuer not available |
> | 977 | Invalid Payment Plan |
> | 978 | Invalid Payment Times |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.