> 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/reference/error-codes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.