Errors

Understand error responses, status codes, and how to handle API errors gracefully in your applications.

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

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.

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

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
}

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
}