Error Codes
Understanding and handling API errors.
Error Response Format
All errors return a consistent JSON structure:
{
"error": {
"type": "invalid_request_error",
"message": "Human readable error message",
"code": "ERROR_CODE",
"details": { } // Optional additional info
}
}Error Types
| Type | Description |
|---|---|
| authentication_error | Invalid or missing API key |
| invalid_request_error | Invalid parameters or request body |
| payment_error | Insufficient credits or billing issue |
| rate_limit_error | Too many requests |
| api_error | Internal server error |
HTTP Status Codes
Bad Request
The request was invalid or malformed.
Solution: Check your request body and parameters match the API specification.
{
"error": {
"type": "invalid_request_error",
"message": "Invalid model: unknown-model",
"code": "INVALID_MODEL"
}
}Unauthorized
No valid API key was provided.
Solution: Ensure your API key is correct and included in the Authorization header.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "INVALID_API_KEY"
}
}Payment Required
Your account has insufficient credits.
Solution: Add more credits to your account or check your spending limits.
{
"error": {
"type": "payment_error",
"message": "Insufficient credits. Required: $0.05, Available: $0.00",
"code": "INSUFFICIENT_CREDITS"
}
}Forbidden
The API key doesn't have permission for this action.
Solution: Check that your API key has the required permissions.
{
"error": {
"type": "permission_error",
"message": "API key does not have access to this resource",
"code": "FORBIDDEN"
}
}Not Found
The requested resource doesn't exist.
Solution: Verify the resource ID is correct.
{
"error": {
"type": "not_found_error",
"message": "Prediction not found: pred_invalid",
"code": "NOT_FOUND"
}
}Conflict
A request with this idempotency key was already processed.
Solution: Use a new idempotency key or retrieve the cached response.
{
"error": {
"type": "idempotency_error",
"message": "A request with this idempotency key already exists",
"code": "DUPLICATE_REQUEST"
}
}Too Many Requests
You've exceeded the rate limit.
Solution: Wait and retry. Check the Retry-After header.
{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded. Try again in 30 seconds.",
"code": "RATE_LIMITED"
}
}Internal Server Error
Something went wrong on our end.
Solution: Retry the request. If it persists, contact support.
{
"error": {
"type": "api_error",
"message": "Internal server error",
"code": "INTERNAL_ERROR"
}
}Service Unavailable
The service is temporarily unavailable.
Solution: Wait a few minutes and retry. Check the status page.
{
"error": {
"type": "service_error",
"message": "Service temporarily unavailable",
"code": "SERVICE_UNAVAILABLE"
}
}Handling Errors
Here's an example of how to handle errors in your code:
try {
const response = await fetch('https://api.deepcreativelabs.com/v1/black-forest-labs/flux-kontext-max/predictions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ input })
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 401:
throw new Error('Invalid API key');
case 402:
throw new Error('Insufficient credits');
case 429:
const retryAfter = response.headers.get('Retry-After');
await sleep(retryAfter * 1000);
return retry();
default:
throw new Error(error.error.message);
}
}
return await response.json();
} catch (error) {
console.error('API Error:', error);
}