Error Handling

The Meirra API uses conventional HTTP status codes to indicate success or failure of requests. In general: • **2xx** - Success. The request worked as expected. • **4xx** - Client error. The request was invalid or cannot be served. • **5xx** - Server error. Something went wrong on our end. All error responses include a consistent JSON structure with an error code, message, and relevant details to help you diagnose and handle the issue.

All errors follow a consistent format: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable error description", "details": { ... } } } ``` The `code` field is a machine-readable error code you can use in your error handling logic. The `message` provides a human-readable description. The optional `details` object contains additional context specific to the error type.

Authentication errors occur when your API key is missing, invalid, or lacks permission. | Code | HTTP | Description | |------|------|-------------| | `INVALID_API_KEY` | 401 | API key is missing or invalid | | `API_KEY_REVOKED` | 401 | API key has been revoked | | `IP_NOT_ALLOWED` | 403 | Request IP not in allowlist | **Example:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The provided API key is invalid or missing" } } ``` **How to fix:** Verify your API key is correct and included in the `x-api-key` header. Check if the key has been revoked in your Developer Dashboard.

Balance errors occur when your account has insufficient credits for the request. | Code | HTTP | Description | |------|------|-------------| | `INSUFFICIENT_BALANCE` | 402 | Balance too low for request | **Example:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your balance of $0.50 is insufficient for this request ($1.00 required)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **How to fix:** Top up your account balance in the Developer Dashboard. Consider setting up low balance alerts to avoid interruptions.

Rate limit errors occur when you exceed the allowed request rate. | Code | HTTP | Description | |------|------|-------------| | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | **Example:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Retry after 60 seconds.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **How to fix:** Implement exponential backoff. Check the `Retry-After` header for when to retry. Consider spreading requests over time.

Validation errors occur when request parameters are missing or invalid. | Code | HTTP | Description | |------|------|-------------| | `INVALID_REQUEST` | 400 | Missing or invalid parameters | | `INVALID_EMAIL` | 400 | Email format is invalid | | `BATCH_TOO_LARGE` | 400 | Batch exceeds maximum size | **Example:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Request validation failed", "details": { "field": "email", "issue": "Email is required" } } } ``` **How to fix:** Check the `details` field for the specific validation failure. Ensure all required fields are provided and match the expected format.

Service errors occur when something goes wrong on our infrastructure. | Code | HTTP | Description | |------|------|-------------| | `SERVICE_ERROR` | 500 | Internal service failure | | `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable | | `UPSTREAM_ERROR` | 502 | External service dependency failed | **Example:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "An internal error occurred. Please try again later." } } ``` **How to fix:** These are transient errors. Implement retry logic with exponential backoff. If errors persist, check the status page or contact support.