Advanced

Error Codes

LinkHarbor uses conventional HTTP response codes to indicate the success or failure of an API request. This page lists the most common errors and how to handle them.

Error Response Format

All errors follow a consistent JSON structure with a top-level error object.

JSON

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common HTTP Status Codes

400

Invalid request

The request body is malformed or missing required fields.

401

Unauthorized

Your API key is invalid, expired, missing, or sent with the wrong header format for the selected interface.

402

Insufficient quota

Your account balance is too low to complete this request.

404

Model not found

The requested model ID does not exist or is not available in your region.

429

Rate limit exceeded

You have sent too many requests. Please retry after the Retry-After header period.

500

Internal server error

An unexpected error occurred on our side. Please retry with exponential backoff.

502

Upstream provider error

The upstream AI provider returned an error. Fallback may be attempted when routing or fallback is configured.

Retry & Debugging Guidance

For 5xx errors, retry with exponential backoff (1s, 2s, 4s). For 429 errors, respect Retry-After when present.

Log the HTTP status, response body, endpoint path, model ID, and timestamp for support and debugging.
For 401 errors, verify that OpenAI-compatible calls use Authorization: Bearer and Anthropic-compatible calls use x-api-key plus anthropic-version.
For repeated 5xx or 502 errors, retry with backoff and verify whether the selected upstream model/provider is available.