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

# Error codes

# Exhaustive Error Code Catalog

fype uses standardized error codes to help you programmatically handle issues. All errors include an `error_code`, a `message`, and an optional `details` array.

## Client Errors (4xx)

| Error Code             | HTTP Status | Description                                                | Recommended Action                                                         |
| :--------------------- | :---------- | :--------------------------------------------------------- | :------------------------------------------------------------------------- |
| `VALIDATION_ERROR`     | 422         | Input validation failed (e.g., invalid email format).      | Check the `details` field for specific field errors.                       |
| `IDEMPOTENCY_CONFLICT` | 409         | `Idempotency-Key` reused with different parameters.        | Use a unique key per intent, or identical params for retries.              |
| `CONFLICT`             | 409         | Resource already exists (e.g. signup with existing email). | Use a different unique identifier or login.                                |
| `API_KEY_REVOKED`      | 401         | The API key has been deleted/revoked.                      | Generate a new key in the dashboard.                                       |
| `API_KEY_INVALID`      | 401         | The API key provided does not exist.                       | Double-check the key in your dashboard.                                    |
| `MISSING_AUTH`         | 401         | Authorization header is required.                          | Include `Authorization: Bearer <key>` header.                              |
| `INVALID_CREDENTIALS`  | 401         | Incorrect email or password during dashboard login.        | Check your credentials.                                                    |
| `MERCHANT_NOT_FOUND`   | 401         | Merchant account associated with key doesn't exist.        | Contact support.                                                           |
| `INVALID_TOKEN`        | 401         | Dashboard JWT session is invalid or expired.               | Log out and log back in to the dashboard.                                  |
| `FORBIDDEN`            | 403         | You do not have access to this resource.                   | Verify you are using the correct merchant context.                         |
| `NOT_FOUND`            | 404         | The resource (Payment, Refund, etc.) was not found.        | Verify the ID in your request.                                             |
| `GONE`                 | 410         | The resource (e.g., Checkout Session) has expired.         | Initiate a new payment request.                                            |
| `RATE_LIMIT_EXCEEDED`  | 429         | Too many requests sent in a short period.                  | Implement exponential backoff.                                             |
| `INVALID_CURSOR`       | 400         | The pagination cursor provided is invalid or malformed.    | Ensure you are passing the exact `next_cursor` from the previous response. |
| `BAD_REQUEST`          | 400         | Generic bad request or malformed payload.                  | Check your JSON structure and required fields.                             |

## Server Errors (5xx)

| Error Code       | HTTP Status | Description                                                  | Recommended Action                                     |
| :--------------- | :---------- | :----------------------------------------------------------- | :----------------------------------------------------- |
| `INTERNAL_ERROR` | 500         | An unexpected error occurred on fype servers.                | Retry the request after a few seconds.                 |
| `GATEWAY_ERROR`  | 502         | The payment provider (Razorpay, Cashfree) returned an error. | Check the error message for details from the provider. |

## SDK Mapping

If you are using our SDKs, these errors are raised as typed exceptions:

### Node.js

* `fypeAuthenticationError` (401)
* `fypeInvalidRequestError` (400, 422, 404, 409)
* `fypeApiConnectionError` (500, 502, timeouts)
* `fypeError` (Generic fallback)

### Python

* `AuthenticationError` (401)
* `InvalidRequestError` (400, 422, 404, 409, 410)
* `ApiConnectionError` (500, 502, timeouts)
* `fypeError` (Generic fallback)

## Webhook Verification Errors

If signature verification fails on your server, the SDK will throw a:

* **Node.js**: `fypeSignatureVerificationError`
* **Python**: `SignatureVerificationError`

This usually means your **Webhook Secret (`whsec_...`)** is mismatched or you are not passing the **raw** request body for verification.