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
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.