---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# Errors
Understand error responses, status codes, and how to handle API errors gracefully in your applications.
**Category:** Getting Started
## Overview

The Hoko API uses standard HTTP status codes to indicate the result of API requests. All error responses follow a consistent, predictable format that makes error handling straightforward in your applications.

Error messages are provided in both English and Arabic, allowing you to display user-friendly error messages regardless of your application's language preference.

Understanding error responses helps you build robust integrations that gracefully handle edge cases and provide clear feedback to users.

## HTTP Status Codes

The API uses standard HTTP status codes to communicate request outcomes. Familiarize yourself with these codes to implement proper error handling:

- 400 Bad Request - The request is malformed, contains invalid parameters, or violates API constraints. Check your request format and parameters.
- 401 Unauthorized - Authentication failed. The API key is missing, invalid, expired, or revoked. Verify your API key is correct and active.
- 403 Forbidden - The API key is valid but lacks the required permission scopes for this operation. Check the missingScopes field in the response.
- 404 Not Found - Returned for unknown endpoints. Resource validation errors are reported as 400 Bad Request.
- 429 Too Many Requests - Rate limit exceeded. Wait for the retryAfter period before making additional requests.
- 500 Internal Server Error - An unexpected server error occurred. These are rare; if you encounter this, contact support with request details.

> **Info: Error Handling Strategy**
> Implement comprehensive error handling that checks status codes and displays appropriate messages to users. For 4xx errors, the issue is typically with the request. For 5xx errors, retry with exponential backoff.

## Error Response Format

All error responses follow a consistent structure. The error object contains bilingual messages, and additional fields provide context-specific information depending on the error type.

**Error Format**

```json
{
  "error": {
    "en": "Error message in English",
    "ar": "رسالة خطأ بالعربية"
  },
  "missingScopes": ["linksWrite"], // Only for 403 errors
  "retryAfter": 45 // Only for 429 errors
}
```

> **Tip: Error Message Selection**
> Use the appropriate language field (en or ar) from the error object based on your application's language preference or user settings.

## Error Examples

Here are examples of common error responses you might encounter:

**400 Bad Request**

```json
{
  "error": {
    "en": "Invalid request format",
    "ar": "تنسيق طلب غير صالح"
  }
}
```

**401 Unauthorized**

```json
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}
```

**403 Forbidden**

```json
{
  "error": {
    "en": "Missing required scopes",
    "ar": "الصلاحيات المطلوبة مفقودة"
  },
  "missingScopes": ["linksWrite", "collectionsWrite"]
}
```

**429 Too Many Requests**

```json
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 45
}
```

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)