> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/reference/error-codes.md).

# Error Codes Reference

This page describes the current public error envelope and the main error types and codes used by the Payments API.

## Error response structure

Public API errors use a top-level problem-details-style object.

```json
{
  "code": "request-validation-errors",
  "message": "Request validation failed. Check required fields, data types, and field constraints in API documentation.",
  "type": "invalid-request-error",
  "status": 400,
  "traceId": "0HMVG9K3R5T4J:00000001",
  "params": {
    "invoiceNumber": [
      "Invoice number is required."
    ]
  }
}
```

### Fields

| Field         | Type   | Description                                                   |
| ------------- | ------ | ------------------------------------------------------------- |
| `code`        | string | Stable machine-readable error code.                           |
| `message`     | string | Human-readable message.                                       |
| `type`        | string | Error category. See the next table.                           |
| `status`      | number | HTTP status code.                                             |
| `traceId`     | string | Request correlation identifier for troubleshooting.           |
| `params`      | object | Field-level validation details when available.                |
| `declineCode` | string | Processor decline code when the payment is declined upstream. |

## Error types

The current public error categories are:

| Type                    | Meaning                                                                        |
| ----------------------- | ------------------------------------------------------------------------------ |
| `api-error`             | Generic API, permission, or resource-state errors.                             |
| `invalid-request-error` | Request validation or input problems.                                          |
| `card-error`            | Card or payment-method data is invalid.                                        |
| `processor-error`       | The processor, issuer, or 3DS flow returned an operational decline or failure. |

## Common public codes

The backend defines many codes. The table below focuses on the codes most relevant to public payment integrations.

### API errors

| Code                  | Typical meaning                                                                |
| --------------------- | ------------------------------------------------------------------------------ |
| `unauthorized`        | Authentication failed.                                                         |
| `forbidden`           | The authenticated client is not allowed to perform that action.                |
| `payment-not-found`   | The requested payment does not exist or is not accessible to your credentials. |
| `conflict`            | The request conflicts with the current resource state.                         |
| `service-unavailable` | An upstream or dependent service is temporarily unavailable.                   |
| `timeout`             | The request timed out while waiting for an upstream service.                   |
| `internal-error`      | An internal error occurred.                                                    |

### Invalid request errors

| Code                             | Typical meaning                                             |
| -------------------------------- | ----------------------------------------------------------- |
| `request-validation-errors`      | One or more request fields failed validation.               |
| `merchant-not-found`             | The merchant ID is invalid or not available to your client. |
| `currency-not-found`             | The supplied currency is not supported.                     |
| `payment-invalid-amount`         | The amount is invalid.                                      |
| `payment-invalid-invoice-number` | `invoiceNumber` is missing or invalid.                      |
| `duplicated-reference-id`        | The `referenceId` already exists.                           |
| `invalid-browser-details`        | Browser data required for the flow is missing or invalid.   |

### Card errors

| Code                                | Typical meaning                                                        |
| ----------------------------------- | ---------------------------------------------------------------------- |
| `invalid-card-number`               | The card number failed validation.                                     |
| `invalid-card-cvc`                  | The CVC or CVV is invalid.                                             |
| `invalid-card-expiration-date`      | The expiration date is invalid or in the past.                         |
| `invalid-cardholder`                | Cardholder data is incomplete or invalid.                              |
| `invalid-card-payment-method`       | The requested payment method is not enabled or valid for the merchant. |
| `invalid-card-payment-method-token` | The stored payment token is invalid or expired.                        |

### Processor errors

| Code                        | Typical meaning                                      |
| --------------------------- | ---------------------------------------------------- |
| `declined-by-acquirer`      | The processor or issuer declined the payment.        |
| `authentication-required`   | The payment requires a 3DS authentication step.      |
| `authentication-failed`     | The 3DS authentication step failed or was cancelled. |
| `acquirer-offline`          | The processor is temporarily unavailable.            |
| `funds-verification-failed` | Payment-method verification failed.                  |

## Example responses

### Validation error

```json
{
  "code": "request-validation-errors",
  "message": "Request validation failed. Check required fields, data types, and field constraints in API documentation.",
  "type": "invalid-request-error",
  "status": 400,
  "traceId": "0HMVG9K3R5T4J:00000001",
  "params": {
    "invoiceNumber": [
      "Invoice number is required."
    ]
  }
}
```

### Processor decline

```json
{
  "code": "declined-by-acquirer",
  "message": "Payment declined by acquirer. Check response code and reason in transaction details. Common causes: insufficient funds, card restrictions, or issuer decline.",
  "type": "processor-error",
  "status": 422,
  "traceId": "0HMVG9K3R5T4J:00000002",
  "declineCode": "05"
}
```

## Integration guidance

* Use the HTTP status first to determine the broad failure class.
* Use `code` for application logic and branching.
* Use `params` to map validation failures to specific request fields.
* Log `traceId` in your own systems so you can correlate support cases.
* Treat `declineCode` as optional. It is only present for some processor-side declines.

## Related resources

* [Authentication](/rest-api/getting-started/authentication.md)
* [Payment Processing Guide](/rest-api/payments/payment-processing.md)
* [Verifying a Payment Method](/rest-api/payments/payment-method-verification.md)