Error Handling
In this guide, we'll explain what happens when something goes wrong while you work with Thesean API. Understanding error responses will help you debug issues and build robust integrations.
You can tell if your request was successful by checking the HTTP status code in the response. If a response is unsuccessful, you can use the error message and details to understand what went wrong.
Most errors are caused by incorrect API usage, such as invalid parameters, missing authentication, or insufficient credits. Always check your request format and API key before contacting support.
HTTP Status Codes
The Thesean API uses standard HTTP status codes to indicate the success or failure of requests.
- Name
200 - OK- Description
The request was successful. The response body contains the requested data.
- Name
400 - Bad Request- Description
The request was malformed or contains invalid parameters. Check your request body and parameters.
- Name
401 - Unauthorized- Description
Authentication failed. Your API key is missing, invalid, or has been revoked.
- Name
403 - Forbidden- Description
You don't have permission to access this resource. Check your account status and credits.
- Name
404 - Not Found- Description
The requested resource or endpoint doesn't exist. Check your URL and model name.
- Name
422 - Unprocessable Entity- Description
The request was well-formed but contains semantic errors (e.g., unsupported model parameters).
- Name
429 - Too Many Requests- Description
You've hit the rate limit. Implement backoff and retry logic.
- Name
500 - Internal Server Error- Description
An unexpected error occurred on our servers. Try again or contact support if it persists.
- Name
503 - Service Unavailable- Description
The service is temporarily unavailable. The upstream provider may be down. Try again later.
Error Response Format
When an error occurs, the Thesean API returns a JSON response with error details:
Anthropic-Compatible Format
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
}
Common Error Types
Authentication Errors
Error Code: 401 Unauthorized
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
Common causes:
- Missing
Authorizationheader - Incorrect API key format
- Revoked or expired API key
Solution: Verify your API key in the Thesean Dashboard and ensure it's correctly formatted in the Authorization: Bearer <API_KEY> header.
Insufficient Credits
Error Code: 403 Forbidden
{
"error": {
"message": "Insufficient credits. Please add credits to your account.",
"type": "insufficient_quota",
"code": "insufficient_credits"
}
}
Solution: Add credits to your account through the Thesean Dashboard.
Invalid Model
Error Code: 404 Not Found or 400 Bad Request
{
"error": {
"message": "The model 'ship-like/unknown-model' does not exist",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}
Common causes:
- Typo in model name
- Model doesn't exist
- Incorrect creator prefix
Solution: Check the Available Models page and use one of the listed
ship-like/ model IDs.
Invalid Parameters
Error Code: 400 Bad Request
{
"error": {
"message": "max_tokens must be a positive integer",
"type": "invalid_request_error",
"param": "max_tokens",
"code": "invalid_parameter"
}
}
Common causes:
- Missing required parameters
- Invalid parameter types
- Out-of-range values
Solution: Review the API Endpoints documentation to ensure all parameters are correctly formatted.
Rate Limiting
Error Code: 429 Too Many Requests
{
"error": {
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
Solution: Implement exponential backoff and respect the Retry-After header. See the retry logic example below.
Provider Errors
Error Code: 503 Service Unavailable
{
"error": {
"message": "The upstream provider is temporarily unavailable",
"type": "api_error",
"code": "provider_unavailable"
}
}
Solution: Retry your request after a delay.
Error Handling Best Practices
Retry Logic with Exponential Backoff
import anthropic
from tenacity import retry, stop_after_attempt, wait_exponential
client = anthropic.Anthropic(
base_url="https://api.thesean.ai",
api_key=THESEAN_API_KEY,
)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=4, max=10),
)
def make_request_with_retry(model, messages):
try:
return client.messages.create(
model=model,
max_tokens=1024,
messages=messages,
)
except anthropic.RateLimitError as e:
print(f"Rate limit hit: {e}")
raise
except anthropic.APIError as e:
print(f"API error: {e}")
raise
response = make_request_with_retry(
model="ship-like/claude-opus-4-8",
messages=[{"role": "user", "content": "Hello!"}],
)
Comprehensive Error Handling
import anthropic
client = anthropic.Anthropic(
base_url="https://api.thesean.ai",
api_key=THESEAN_API_KEY,
)
try:
response = client.messages.create(
model="ship-like/claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.content[0].text)
except anthropic.AuthenticationError as e:
print(f"Authentication failed: {e}")
except anthropic.RateLimitError as e:
print(f"Rate limit exceeded: {e}")
except anthropic.BadRequestError as e:
print(f"Invalid request: {e}")
except anthropic.APIError as e:
print(f"API error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
If you encounter persistent errors or need assistance:
- Check the documentation: Review the API Reference and Examples
- Monitor your usage: Check the Thesean Dashboard for quota and error logs
- Contact support: Email us at support@thesean.ai