> For the complete documentation index, see [llms.txt](https://docs.skypaybd.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skypaybd.top/system-and-devices/error-codes.md). # Error Reference This document provides a comprehensive reference of all HTTP status codes, machine-readable error string constants, operational failure causes, and actionable troubleshooting steps across the SkyPay API platform. *** ## 1. Global HTTP Status Codes SkyPay adheres to standard RESTful HTTP status code semantics: | HTTP Status | Category | Meaning & System Implication | | ------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | **`200 OK`** | Success | Request succeeded. Response body contains valid transaction or telemetry payload. | | **`400 Bad Request`** | Client Error | Malformed JSON, missing required headers/fields, duplicate TrxID, or amount mismatch. | | **`401 Unauthorized`** | Authentication | Missing, malformed, inactive, or invalid `BRAND-KEY`, `GATEWAY-KEY`, or token. | | **`403 Forbidden`** | Authorization | Merchant account suspended by compliance, or IP address not whitelisted. | | **`404 Not Found`** | Resource Missing | Payment session expired, transaction ID not found, or device keys unmatched. | | **`405 Method Not Allowed`** | Protocol | Incorrect HTTP verb used (e.g., executing a `GET` request on a `POST`-only route). | | **`422 Unprocessable Entity`** | Validation | Semantic validation failure (e.g., amount out of range `1` to `1,000,000`, invalid URL syntax). | | **`429 Too Many Requests`** | Rate Limiting | Request threshold exceeded. Backoff required. | | **`500 Internal Server Error`** | Server Error | Database commit error, transaction deadlock, or unhandled internal exception. | | **`502 Bad Gateway`** | Upstream Error | Upstream provider timeout (e.g., BSC decentralized RPC node, Binance Pay API, or FCM relay). | | **`503 Service Unavailable`** | Maintenance | SkyPay Core Engine undergoing scheduled maintenance or temporary rate-limiting. | *** ## 2. Comprehensive System Error Reference Table | HTTP Status | Error String / Constant | Applicable Endpoints | Root Cause | Recommended Troubleshooting Steps | | ----------- | -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **400** | `MISSING_PARAMETERS` | All Endpoints | Required request body fields are absent. | Ensure `amount`, `cus_name`, or `transaction_id` are supplied in valid JSON format. | | **400** | `DUPLICATE_TRANSACTION_ID` | `/api/v2/payment/verify` | The customer-submitted TrxID has already been credited. | Check your internal orders database. Ensure the customer is not reusing an old SMS proof. | | **400** | `AMOUNT_MISMATCH` | `/api/v2/payment/verify` | Transferred amount does not match the session invoice amount. | Prompt customer to send the exact bill amount or issue an adjustment invoice. | | **400** | `DEVICE_OFFLINE` | `/api/v2/gateway/send` | The Android SMS relay device has no assigned IP address or is disconnected. | Inspect the physical Android phone. Verify Wi-Fi/cellular connection and open `SkyPay.apk`. | | **400** | `MISSING_DEVICE_KEYS` | `/api/v2/device/status` | `DEVICE-KEYS` header was omitted from the request. | Provide a comma-separated list of valid device identifiers in the `DEVICE-KEYS` header. | | **401** | `UNAUTHORIZED` | All Endpoints | No authentication header detected. | Pass `BRAND-KEY: ` or `Authorization: Bearer ` in your HTTP request headers. | | **401** | `INVALID_BRAND_KEY` | Payment Endpoints | The provided Brand Key does not match any active merchant. | Verify your credentials in the Merchant Portal under **API Settings**. | | **401** | `INVALID_GATEWAY_KEY` | `/api/v2/gateway/send` | The 18-character SMS gateway key is incorrect or deactivated. | Verify your hardware key in the **SMS Gateway > Devices** tab of the portal. | | **403** | `ACCOUNT_SUSPENDED` | All Endpoints | Merchant account suspended due to compliance, chargeback, or policy issues. | Contact SkyPay Merchant Support at `support@skypaybd.top` to resolve account flags. | | **403** | `IP_FORBIDDEN` | All Endpoints | Request originated from an IP not listed in merchant whitelist. | Update your static server IP list in Merchant Portal **Security > IP Whitelist**. | | **404** | `SESSION_NOT_FOUND` | `/api/v2/payment/verify` | The session `id` is invalid or does not exist. | Verify that the session token returned by `/api/v2/payment/create` was stored correctly. | | **404** | `SESSION_EXPIRED` | `/api/v2/payment/verify` | The payment session exceeded the 15-minute validity window. | Prompt the user to re-initialize a new payment session. | | **404** | `TRANSACTION_NOT_FOUND` | `/api/payment/verify`, `/api/v2/payment/verify` | The TrxID was not found in device SMS logs or blockchain. | Wait 10 seconds and retry. If still absent, verify that the customer sent money to the correct wallet. | | **404** | `NO_MATCHING_DEVICES` | `/api/v2/device/status` | None of the supplied `DEVICE-KEYS` match registered hardware. | Check device key spelling and ensure the device was not deleted from the merchant dashboard. | | **405** | `METHOD_NOT_ALLOWED` | All Endpoints | Incorrect HTTP method used (e.g. `GET` on `/api/v2/payment/create`). | Verify API documentation and switch to `POST`. | | **422** | `OUT_OF_BOUNDS_AMOUNT` | `/api/payment/create` | Bill amount is `< 1.00` or `> 1,000,000.00` BDT. | Restrict payment amounts to the allowed range (1 BDT to 1,000,000 BDT). | | **422** | `INVALID_URL_SYNTAX` | `/api/payment/create` | `success_url` or `cancel_url` is not an absolute HTTPS URL. | Ensure all return URLs include the `https://` protocol and a valid domain name. | | **429** | `RATE_LIMIT_EXCEEDED` | All Endpoints | Merchant exceeded rate limit (e.g., > 120 requests/minute). | Implement exponential backoff and jitter in client requests. Cache non-critical queries. | | **500** | `DATABASE_COMMIT_FAILED` | All Endpoints | Database deadlocked during concurrent transaction commitment. | Retry request after 2 seconds. The transaction state remains uncommitted. | | **502** | `BSC_RPC_TIMEOUT` | `/api/v2/payment/verify` | Binance Smart Chain RPC node failed to return block receipt in 10s. | Retry verification after 10 seconds. SkyPay automatically fails over to backup RPC nodes. | | **502** | `BINANCE_API_TIMEOUT` | `/api/v2/payment/verify` | Binance Pay Open API connection timed out. | Retry verification after 5 seconds. | | **502** | `FCM_DISPATCH_FAILURE` | `/api/v2/gateway/send` | Firebase Cloud Messaging failed to wake up target Android phone. | Verify the relay phone has an active internet connection and Google Play Services enabled. | *** ## 3. Standard Error JSON Schemas All error responses from SkyPay return a structured JSON object containing a `status: false` flag and a human-readable `message`: ### Standard Error Payload ```json { "status": false, "message": "The amount must be between 1 and 1000000." } ``` ### Detailed Validation Error Payload (HTTP 422) ```json { "status": false, "message": "Validation failed.", "errors": { "amount": ["The amount field is required."], "success_url": ["The success_url must be a valid URL."] } } ``` *** ## 4. Diagnostic & Troubleshooting Workflow When troubleshooting payment integration errors, follow this structured diagnostic workflow: ``` ┌──────────────────────────────────────┐ │ API Request Failed? │ └──────────────────┬───────────────────┘ │ ┌────────────────┴────────────────┐ ▼ ▼ [HTTP 4xx Error] [HTTP 5xx Error] │ │ ┌───────┴───────┐ ┌───────┴───────┐ ▼ ▼ ▼ ▼ [401 / 403] [400 / 422] [502] [500] Credential Payload / Schema Upstream Node Database Inspection Validation Timeout/Retry Deadlock │ │ │ │ ▼ ▼ ▼ ▼ Verify .env Check Data Types Retry in 10s Retry with & IP Rules & Constraints Auto-Failover Backoff ``` ### Step-by-Step Diagnostic Checklist 1. **Verify Transport & Headers**: Ensure request is sent via HTTPS with `Content-Type: application/json` and `Accept: application/json`. 2. **Inspect Authentication**: Confirm the exact spelling of `BRAND-KEY` or `GATEWAY-KEY`. 3. **Check Telecom Latency**: If verifying MFS SMS transactions (bKash/Nagad), confirm that at least 15 seconds have elapsed since customer transfer before concluding the TrxID is missing. 4. **Examine Device State**: Call `/api/v2/device/status` to ensure your relay phone is `online` (`status: 1`) and not `offline` (`status: 2`). 5. **Inspect Webhook Logs**: If webhooks are failing, check your server's access logs for incoming `POST` requests and verify that your server returns `HTTP 200` within 5 seconds. *** ## 5. Next Steps Review the platform release notes and versioning history: * [← Previous: Device Health & Telemetry](/system-and-devices/devices-telemetry.md) * [Next: Changelog →](/system-and-devices/changelog.md)