Error Codes & Troubleshooting
Comprehensive reference for Dictionary API status codes, system errors, and recommended resolution steps.
| Error Code | Category | HTTP Status | Description | Recommended Action |
|---|---|---|---|---|
| 400 | Client Error | 400 | Bad Request. The request body is malformed, missing required fields, or contains invalid syntax. | Validate JSON structure and ensure all required parameters are present. |
| 401 | Authentication | 401 | Unauthorized. Missing or invalid API key in the Authorization header. | Verify your API key is active and correctly formatted as `Bearer <key>`. |
| 403 | Client Error | 403 | Forbidden. Valid authentication, but insufficient permissions for the requested resource. | Check API plan limits and endpoint access permissions in your dashboard. |
| 404 | Client Error | 404 | Not Found. The requested word, translation, or resource does not exist. | Verify the endpoint URL, language code, or search term spelling. |
| DIC_1001 | Validation | 422 | Word Not Found in Database. The submitted term is not indexed in the Dictionary corpus. | Use the `suggest` endpoint for similar terms or request corpus expansion via support. |
| DIC_1002 | Validation | 422 | Invalid Language Code. The provided ISO 639-1 code is unsupported or malformed. | Refer to the Supported Languages list and ensure lowercase formatting (e.g., `en`, `es`). |
| 429 | Client Error | 429 | Too Many Requests. Rate limit exceeded for your API tier. | Implement exponential backoff. Check `X-RateLimit-Reset` header for cooldown time. |
| DIC_2001 | System | 503 | Translation Service Unavailable. Downstream language model is experiencing high load. | Retry with delay. Monitor status page for service health updates. |
| DIC_2002 | System | 500 | Audio Generation Failed. TTS engine could not synthesize pronunciation for the term. | Fallback to phonetic text. Report edge-case words via developer portal. |
| 500 | Server Error | 500 | Internal Server Error. Unexpected failure in the Dictionary backend processing pipeline. | Check request payload for special characters. Retry once; contact support if persistent. |
| 502 | Server Error | 502 | Bad Gateway. Upstream dependency or database cluster returned invalid response. | Temporary issue. Retry after 5-10 seconds. Review status dashboard for maintenance alerts. |
| 503 | Server Error | 503 | Service Unavailable. Scheduled maintenance or automatic failover in progress. | Defer non-critical requests. Estimated resolution time provided in response headers. |