Error Codes

Reference for all error responses returned by the WikiRest API.

Error response format

All errors return a JSON object with the following structure:

{
  "error": "error_code",
  "message": "Human-readable description of the error",
  "details": {} // Optional additional information
}

HTTP status codes

Error code reference

Authentication errors

unauthorized

HTTP 401 - No API key provided

{
  "error": "unauthorized",
  "message": "API key required. Include X-API-Key header."
}

Solution: Add your API key to the request headers.

forbidden

HTTP 403 - Invalid, expired, or revoked API key

{
  "error": "forbidden",
  "message": "Invalid or revoked API key."
}

Solution: Check your API key is correct. If revoked, create a new one.

Validation errors

invalid_parameter

HTTP 400 - A parameter has an invalid value

{
  "error": "invalid_parameter",
  "message": "Parameter 'limit' must be between 1 and 50",
  "details": {
    "parameter": "limit",
    "value": 100,
    "constraint": "1-50"
  }
}

Solution: Check the parameter constraints in the API reference.

missing_parameter

HTTP 400 - A required parameter is missing

{
  "error": "missing_parameter",
  "message": "Required parameter 'q' is missing",
  "details": {
    "parameter": "q"
  }
}

Solution: Include all required parameters in your request.

Resource errors

not_found

HTTP 404 - The requested resource doesn't exist

{
  "error": "not_found",
  "message": "Chunk not found",
  "details": {
    "resource": "chunk",
    "id": "99999999_1"
  }
}

Solution: Verify the resource ID is correct.

Rate Limit & Quota Errors

Both rate limits and quotas are adjustable based on your plan. Rate limits control requests per minute. Quotas control total requests per month.

rate_limit_exceeded

HTTP 429 - Per-minute rate limit exceeded (too many requests too fast)

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retry_after": 45
}

Headers: Check Retry-After for seconds to wait.

Solution: Slow down requests. Add delays or implement exponential backoff. Upgrade your plan for higher per-minute limits.

quota_exceeded

HTTP 429 - Monthly quota exceeded (used all requests for the month)

{
  "error": "quota_exceeded",
  "message": "Monthly quota exceeded.",
  "quota_limit": 5000,
  "quota_used": 5000,
  "retry_after": 86400
}

Headers: Check Retry-After for seconds until quota resets.

Solution: Wait for reset or upgrade your plan for higher monthly quotas. Paid plans include overage pricing.

Server errors

internal_error

HTTP 500 - Unexpected server error

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again."
}

Solution: Retry the request. If persistent, contact support.

service_unavailable

HTTP 503 - Service temporarily unavailable

{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable. Please try again later.",
  "details": {
    "retry_after": 30
  }
}

Solution: Wait and retry. Check status page.

Handling errors in code

Python

import requests

response = requests.get(url, headers=headers, params=params)

if response.status_code != 200:
    error = response.json()
    if response.status_code == 429:
        retry_after = error.get("details", {}).get("retry_after", 60)
        print(f"Rate limited. Retry after {retry_after}s")
    elif response.status_code == 401:
        print("Check your API key")
    else:
        print(f"Error: {error['message']}")

JavaScript

const response = await fetch(url, { headers });

if (!response.ok) {
  const error = await response.json();

  switch (response.status) {
    case 429:
      const retryAfter = error.details?.retry_after || 60;
      console.log(`Rate limited. Retry after ${retryAfter}s`);
      break;
    case 401:
      console.log("Check your API key");
      break;
    default:
      console.log(`Error: ${error.message}`);
  }
}