> For the complete documentation index, see [llms.txt](https://moonie.gitbook.io/mooniepay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://moonie.gitbook.io/mooniepay/introduction/errors.md). # Errors The MooniePay API is RESTful and uses conventional HTTP response codes to indicate the success or failure of a request. In addition to the HTTP status code, every error response includes a machine-readable `code` field drawn from a fixed set of error codes — making it easy to handle specific scenarios programmatically. *** ### HTTP Status Code Summary * Codes in the **2xx** range mean the request was processed successfully. * Codes in the **4xx** range mean something was wrong with your request — missing headers, invalid credentials, wrong parameters, or insufficient permissions. * Codes in the **5xx** range indicate an unexpected error on MooniePay's side. *** ### Common HTTP Status Codes | Code | Status | Description | | ----- | ------------------------- | --------------------------------------------------------------------------------------------- | | `200` | **OK** | Request was successful. | | `201` | **Created** | Request succeeded and a new resource was created. | | `202` | **Accepted** | Request was acknowledged and is being processed asynchronously. | | `400` | **Bad Request** | Malformed request, invalid environment, or missing required parameters. | | `401` | **Unauthorized** | Missing or invalid authentication headers, API key, timestamp, or signature. | | `403` | **Forbidden** | The API key is valid but not authorized to access this resource (e.g. IP not whitelisted). | | `404` | **Not Found** | The requested resource does not exist. | | `413` | **Payload Too Large** | The request body exceeds the allowed size limit. | | `422` | **Unprocessable Entity** | All required parameters were provided but failed validation. | | `429` | **Too Many Requests** | You have exceeded the rate limit. Wait before retrying. | | `500` | **Internal Server Error** | An unexpected error occurred on MooniePay's servers. Retry after a moment or contact support. | | `503` | **Service Unavailable** | MooniePay is temporarily offline for maintenance. Try again later. | *** ### Error Response Format Every error response follows this structure: ```json { "success": false, "code": "INVALID_API_KEY", "message": "Invalid API key.", "errors": [] } ``` The `code` field is the key to programmatic error handling. It will always be one of the values listed in the table below. *** ### MooniePay Error Codes Error codes are grouped by category to help you understand the context of each failure. *** #### 🔐 Authentication Errors These errors occur when the request headers are missing, malformed, expired, or cryptographically invalid. | Code | HTTP | Description | | --------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ | | `AUTHENTICATION_HEADERS_REQUIRED` | `401` | One or more of the four required headers (`Authorization`, `X-TTUM-Timestamp`, `X-TTUM-Signature`, `X-TTUM-Environment`) is missing. | | `INVALID_TIMESTAMP` | `401` | The `X-TTUM-Timestamp` header is not a valid positive integer. | | `TIMESTAMP_EXPIRED` | `401` | The timestamp is outside the allowed ±5 minute window. Generate a fresh timestamp for every request. | | `INVALID_DIGITAL_SIGNATURE` | `401` | The `X-TTUM-Signature` does not match the server's computed HMAC. Verify your canonical string and secret key. | | `INVALID_ENVIRONMENT` | `400` | The `X-TTUM-Environment` header is not `sandbox` or `live`. | | `INVALID_API_KEY` | `401` | The API key is not found, disabled, inactive, or is the wrong type for this endpoint. | | `API_KEY_ENV_MISMATCH` | `401` | The API key belongs to a different environment than the one declared in `X-TTUM-Environment`. | | `FORBIDDEN` | `403` | The request IP address is not in the API key's whitelisted IPs. | *** #### 🏢 Application Errors These errors relate to the state or configuration of your MooniePay application. | Code | HTTP | Description | | ----------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | | `APPLICATION_NOT_ACTIVE` | `403` | Your application exists but has not been activated. Contact support or check your dashboard. | | `APP_NOT_ACTIVE` | `403` | The application associated with this API key is currently inactive. | | `LIVE_MODE_NOT_ENABLED` | `403` | Your application has not been approved to process live transactions. Complete the onboarding process to enable live mode. | | `ENVIRONMENT_CONTEXT_NOT_SET` | `500` | Invironment context not set | *** #### 💳 Payment Errors These errors occur when initiating or retrieving payment transactions. | Code | HTTP | Description | | -------------------------------- | ----- | ---------------------------------------------------------------------------------------------------- | | `PAYMENT_NOT_FOUND` | `404` | No payment was found for the provided ID. Verify the payment ID and environment. | | `PAYMENT_METHOD_NOT_ENABLED` | `406` | Payment method disabled. | | `PAYMENT_METHOD_NOT_SUPPORTED` | `406` | The method doesn't support payment feature | | `APP_PAYMENT_METHOD_NOT_ENABLED` | `406` | Payment method is available but not enable for this application. Please enable it on the dashboard. | *** #### 💸 Payout Errors These errors occur when initiating or retrieving payout transactions. | Code | HTTP | Description | | ------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | | `PAYOUT_NOT_FOUND` | `404` | No payout was found for the provided ID. Verify the payout ID and environment. | | `INSUFFICIENT_FUNDS` | `422` | Your MooniePay balance does not have enough funds to cover this payout. Top up your account and retry. | | `PAYOUT_NOT_AVAILABLE` | `422` | Payouts are currently unavailable for the selected method or destination. | | `PAYOUT_METHOD_NOT_SUPPORTED` | `406` | Method doesn't support payout transaction. | | `APP_PAYOUT_METHOD_NOT_ENABLED` | `406` | Payout method is available but not enable for this application. Please enable it on the dashboard. | | `PAYOUT_METHOD_NOT_ENABLED` | `406` | Payout method disabled. | *** #### 🌐 General Errors | Code | HTTP | Description | | ------------------- | ----- | ----------------------------------------------------------------- | | `PAYLOAD_TOO_LARGE` | `413` | The request body is too large. Reduce the payload size and retry. | > 💡 **Tip:** When debugging in Postman, open the **Console** (`View → Show Postman Console`) to see the full response including `code` and `errors`. This makes it much faster to identify which step in the authentication chain failed. --- # 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://moonie.gitbook.io/mooniepay/introduction/errors.md?ask=&goal= ``` `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.