> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysway.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

PaySway uses standard HTTP response codes to indicate the success or failure of an API request.

* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate a client error (e.g., a required parameter was omitted, validation failed, etc.).
* Codes in the `5xx` range indicate an error with PaySway's servers (these are rare).

Some `4xx` errors include an error code to identify the specific issue (e.g., access token is invalid).

## Error response

PaySway returns an error response for `4xx` and `5xx` status codes with the following fields:

<ResponseField name="code" type="enum">
  A unique error code identifying the specific issue. Only included for well-known errors. See the error codes section below for possible values.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message providing details about the error. Intended for developers and may contain technical information.
</ResponseField>

## Error codes

Below is a reference of PaySway error codes, including descriptions and resolution guidance where applicable.

### Idempotency errors

| Error code                            | Error description                                                                                                                                            |
| :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *IDEMPOTENCY\_KEY\_HEADER\_MISSING*   | The required `Idempotency-Key` header is missing.                                                                                                            |
| *IDEMPOTENCY\_KEY\_REQUEST\_MISMATCH* | Idempotency keys can only be used with the same parameters they were first used with. Try using a different key if you meant to execute a different request. |

### Metadata errors

| Error code                  | Error description                                                                                                               |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| *METADATA\_TOO\_MANY\_KEYS* | Too many metadata entries. Maximum allowed is 10.                                                                               |
| *METADATA\_INVALID\_KEY*    | Invalid metadata key. Keys must match `^[A-Za-z0-9._-]{1,40}$` (1-40 characters: letters, numbers, dots, underscores, hyphens). |
| *METADATA\_INVALID\_VALUE*  | Invalid metadata value. Values must be strings with maximum length of 250 characters.                                           |

### Authentication errors

| Error code                           | Error description                                                                              |
| :----------------------------------- | :--------------------------------------------------------------------------------------------- |
| *AUTH\_MISSING\_CLIENT\_CREDENTIALS* | Client credentials are missing.                                                                |
| *AUTH\_INVALID\_CLIENT\_CREDENTIALS* | Provided client credentials are invalid.                                                       |
| *AUTH\_M2M\_TOKEN\_NOT\_FOUND*       | No M2M access token found. Please provide your M2M access token in the `Authorization` header. |
| *AUTH\_M2M\_TOKEN\_INVALID*          | Provided M2M token is expired, malformed, or invalid for other reasons.                        |

### Webhook errors

| Error code                               | Error description                                             |
| :--------------------------------------- | :------------------------------------------------------------ |
| *WEBHOOK\_SUBSCRIPTIONS\_LIMIT\_REACHED* | The maximum number of webhook subscriptions has been reached. |
| *WEBHOOK\_ENDPOINT\_URL\_INVALID*        | The endpoint URL does not meet the specified requirements.    |
| *WEBHOOK\_ENDPOINT\_ALREADY\_SUBSCRIBED* | A webhook subscription with this endpoint URL already exists. |