> For the complete documentation index, see [llms.txt](https://docs.cryptoix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cryptoix.io/developers/rate-limits-and-errors.md). # Rate Limits and Errors This document outlines the rate limits imposed on the Cryptoix API and provides guidance on understanding and handling API error responses. Adhering to these guidelines will ensure stable and efficient integration with the Cryptoix platform. ## API Rate Limits To ensure fair usage and maintain the performance and reliability of our platform, the Cryptoix API enforces rate limits on incoming requests. These limits are applied per API key. * **Requests per Minute:** `500` requests * **Requests per Hour:** `10,000` requests * **Requests per Day:** `100,000` requests **Note:** These rate limits are configurable and may vary. For specific, potentially stricter limits on critical endpoints, please refer to the individual endpoint documentation. Exceeding these limits will result in a `429 Too Many Requests` HTTP status code. The response will include a `Retry-After` header indicating the duration in seconds to wait before making another request. ## Understanding Error Codes The Cryptoix API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the API will return a JSON response containing an `error` object with detailed information. ### Common HTTP Status Codes | Status Code | Description | | --------------------------- | ---------------------------------------------------------------------------- | | `200 OK` | The request was successful. | | `201 Created` | The request was successful, and a new resource was created. | | `204 No Content` | The request was successful, but there is no content to return. | | `400 Bad Request` | The request was malformed or invalid. | | `401 Unauthorized` | Authentication credentials are missing or invalid. | | `403 Forbidden` | The authenticated user does not have permission to perform the action. | | `404 Not Found` | The requested resource could not be found. | | `405 Method Not Allowed` | The HTTP method used is not supported for this endpoint. | | `409 Conflict` | The request could not be completed due to a conflict with the current state. | | `422 Unprocessable Entity` | The request was well-formed but contained semantic errors. | | `429 Too Many Requests` | The rate limit for the API key has been exceeded. | | `500 Internal Server Error` | An unexpected error occurred on the server. | | `503 Service Unavailable` | The server is temporarily unable to handle the request. | ### Error Response Structure When an error occurs (typically for `4xx` or `5xx` status codes), the API will return a JSON response with the following structure: ```json { "error": { "code": "INVALID_PARAMETER", "message": "The 'amount' parameter must be a positive number.", "details": { "parameter": "amount", "value": "-10.00", "rule": "positive_numeric" } } } ``` * **`code`**: A machine-readable error code (e.g., `INVALID_PARAMETER`, `AUTHENTICATION_FAILED`, `RESOURCE_NOT_FOUND`). * **`message`**: A human-readable description of the error. * **`details`** (Optional): Provides additional context about the error, such as the specific parameter that caused the issue, its value, and the validation rule that was violated. #### Example `details` Objects The `details` object can provide varying levels of information depending on the error type. **Validation Errors:** ```json // Example: Invalid data type for 'amount' { "parameter": "amount", "value": "not_a_number", "rule": "numeric" } ``` ```json // Example: Value out of allowed range for 'currency' { "parameter": "currency", "value": "XYZ", "rule": "in:USD,EUR,BTC" } ``` ```json // Example: Missing required field 'callback_url' { "parameter": "callback_url", "rule": "required" } ``` **Authentication/Authorization Errors:** While less common to have detailed `details` for these, they might appear in specific scenarios. ```json // Example: Specific reason for permission denial (hypothetical) { "permission": "read_transactions", "reason": "Account is not yet verified." } ``` ### Common Error Codes and Meanings
Error CodeHTTP StatusDescription
INVALID_API_KEY401The provided API key is invalid, missing, or has been revoked.
AUTHENTICATION_FAILED401The provided authentication credentials are incorrect.
PERMISSION_DENIED403The authenticated user lacks the necessary permissions to perform the requested action.
RESOURCE_NOT_FOUND404The requested resource (e.g., transaction, invoice) does not exist.
INVALID_PARAMETER400 / 422One or more parameters in the request are invalid (e.g., incorrect format, out of range, missing required).
DUPLICATE_ENTRY409A resource with the same unique identifier already exists.
RATE_LIMIT_EXCEEDED429You have exceeded the allowed number of requests within a given time period.
INTERNAL_ERROR500An unexpected error occurred on the Cryptoix server. Please try again later or contact support.
SERVICE_UNAVAILABLE503The Cryptoix service is temporarily unavailable. Please try again later.
## Error Handling Strategies Robust error handling is crucial for building reliable integrations. Your application should be prepared to gracefully handle API errors. {% stepper %} {% step %} ### Check HTTP Status Codes Always inspect the HTTP status code returned by the API. Use this to quickly determine the general nature of the response. {% endstep %} {% step %} ### Parse Error Responses For `4xx` and `5xx` status codes, parse the JSON response body to access the `error.code` and `error.message` for specific details. {% endstep %} {% step %} ### Implement Retry Logic (with Exponential Backoff) * For transient errors like `503 Service Unavailable` or occasional `500 Internal Server Error`, implement a retry mechanism. * Use exponential backoff: start with a short delay (e.g., 1 second) and double the delay for each subsequent retry, up to a maximum delay (e.g., 60 seconds). * Include jitter (randomness) in the backoff delay to prevent multiple clients from retrying simultaneously and overwhelming the server. * Limit the number of retries to avoid infinite loops. {% endstep %} {% step %} ### Handle Specific Error Codes * **`400 Bad Request` / `422 Unprocessable Entity`:** These usually indicate issues with your request payload. Log the error details and inform the user or developer to correct the request. Do not retry without modification. * **`401 Unauthorized` / `403 Forbidden`:** These indicate authentication or authorization problems. Verify your API key and permissions. Do not retry without correcting the credentials or ensuring proper authorization. * **`404 Not Found`:** The resource you are trying to access does not exist. This usually means there's a logic error in your application (e.g., trying to access a non-existent transaction ID). Do not retry. * **`429 Too Many Requests`:** Implement the retry logic with exponential backoff as described above. The Cryptoix API **does send** a `Retry-After` header in `429` responses, indicating how long to wait before making another request. Respect this header when present. {% endstep %} {% step %} ### Logging Log all API errors, including the request details (without sensitive information), the full error response, and any retry attempts. This is invaluable for debugging. {% endstep %} {% step %} ### Alerting Set up alerts for critical or persistent API errors to notify your operations team. {% endstep %} {% endstepper %} ## Best Practices for API Usage To ensure a smooth and efficient experience when integrating with the Cryptoix API: * **Use API Keys Securely:** Treat your API keys like passwords. Do not embed them directly in client-side code or commit them to public repositories. Store them securely on your server. * **Validate Input:** Before sending requests to the API, validate that your data conforms to the expected formats and constraints. This helps prevent `400 Bad Request` or `422 Unprocessable Entity` errors. * **Handle Pagination:** When retrieving lists of resources, use the provided pagination parameters (e.g., `limit`, `offset`, `next_cursor`) to fetch data in manageable chunks. * **Stay Updated:** Keep an eye on API versioning and announcements for any changes or updates to the API. * **Respect Rate Limits:** Implement retry logic with exponential backoff to handle `429 Too Many Requests` errors gracefully. Avoid aggressive polling. * **Use Webhooks:** For real-time event notifications (e.g., payment confirmations), configure and securely handle webhook callbacks from Cryptoix instead of constantly polling for status updates. Ensure your webhook endpoint is robust and can acknowledge receipt quickly. * **Test Thoroughly:** Test your integration in a staging or sandbox environment before deploying to production. Simulate various error conditions to ensure your handling logic is effective. --- # 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://docs.cryptoix.io/developers/rate-limits-and-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.