Errors & Rate Limits

Error Format

All errors return a consistent JSON format:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Status	Meaning
200	Success
201	Created (new API key)
400	Bad request (missing/invalid params)
401	Unauthorized (invalid or missing API key)
403	Forbidden (insufficient permissions)
404	Not found
429	Rate limited
500	Server error

Common Error Codes

Code	Status	Description
`INVALID_API_KEY`	401	API key is invalid, expired, or revoked
`INSUFFICIENT_CREDITS`	400	Not enough credits for this generation
`MISSING_FIELDS`	400	Required fields are missing from the request body
`GENERATION_ERROR`	500	The generation failed to start (upstream model error)
`MODEL_NOT_FOUND`	400	Returned when you pass an invalid model identifier. Use `GET /api/v1/models` to list valid identifiers.
`RATE_LIMITED`	429	Too many requests -- back off and retry after the indicated period

Example: MODEL_NOT_FOUND

Request with an invalid model identifier:

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat", "model": "nonexistent-model"}'

Response (400):

{
  "success": false,
  "error": "Model not found",
  "code": "MODEL_NOT_FOUND"
}

To fix this, omit the model field (Smart Select picks the best model automatically) or fetch valid identifiers first:

curl https://api.kolbo.ai/api/v1/models \
  -H "X-API-Key: YOUR_API_KEY"

Handling Errors (JavaScript)

async function main() {
  const response = await fetch("https://api.kolbo.ai/api/v1/generate/image", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ prompt: "A cat" })
  });

  const data = await response.json();

  if (!response.ok) {
    console.error(`Error ${response.status}: ${data.code} - ${data.error}`);
  } else {
    console.log("Generation started:", data.generation_id);
  }
}
main();

Handling Errors (Python)

import requests

response = requests.post(
    "https://api.kolbo.ai/api/v1/generate/image",
    headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"prompt": "A cat"}
)

data = response.json()

if not response.ok:
    print(f"Error {response.status_code}: {data.get('code')} - {data.get('error')}")
else:
    print(f"Generation started: {data['generation_id']}")

Rate Limits

Endpoint	Limit
Generation endpoints	10 requests/minute per user
Status polling	300 requests/minute per IP
Models / Credits	300 requests/minute per IP

When rate limited, the response includes:

{
  "status": false,
  "message": "Too many requests, please try again later"
}

Generation States

When polling status, the state field can be:

State	Description
`pending`	Generation is queued (Creative Director only)
`processing`	Generation is in progress
`completed`	Generation finished, `result` field contains URLs
`failed`	Generation failed, `error` field explains why
`cancelled`	Generation was cancelled

Handling Failures

Check state in status response
If failed, read the error field
Credits are automatically refunded for failed generations
You can retry with a new request

Timeouts

Chat (POST /v1/chat): requires polling, typically 5-30 seconds
Image: typically completes within 30 seconds
Video: typically completes within 5 minutes
Music: typically completes within 2 minutes
Speech/Sound: typically completes within 30 seconds
Creative Director: typically completes within 3 minutes (depends on scene count)

If polling beyond these times, the generation may have failed silently. Check the status one final time, then consider retrying.

On this page