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:
A unique error code identifying the specific issue. Only included for well-known errors. See the error codes section below for possible values.
A human-readable message providing details about the error. Intended for developers and may contain technical information.
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. |
| 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. |
