Ittybit

Overview

The Ittybit API returns JSON-encoded responses.

Single resource endpoints (e.g. GET /tasks/:id) return the resource object directly
List endpoints (e.g. GET /tasks) return an array of objects
Error responses return an object with kind and message fields

Success Responses

Success responses return data directly — no wrapper object.

Single resource

// GET /tasks/task_abcdefgh12345678
{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "video",
  "status": "succeeded",
  "inputs": [...],
  "outputs": [...],
  "created_at": 1735689825,
  "updated_at": 1735689886
}

List response

// GET /tasks
[
  {
    "id": "task_abcdefgh12345678",
    "object": "task",
    "kind": "video",
    "status": "succeeded"
  },
  {
    "id": "task_abcdefgh90123456",
    "object": "task",
    "kind": "speech",
    "status": "processing"
  }
]

List responses with no results return an empty array ([]), not null or an error.

Error Responses

Error responses include a kind identifier and a human-readable message:

// 404 Not Found
{
  "kind": "task_not_found",
  "message": "The task does not exist. Verify the task ID."
}

// 400 Bad Request
{
  "kind": "request_invalid",
  "message": "The 'kind' field is required."
}

// 401 Unauthorized
{
  "kind": "token_missing",
  "message": "No authorization token was provided."
}

Status Codes

Status Code	Description	When You'll See It
200 OK	Request succeeded	Most common success response
201 Created	Resource created	Returned when a new resource is created via POST
202 Accepted	Request accepted	Request accepted for processing but not yet complete
400 Bad Request	Invalid request	Missing required parameters or invalid values
401 Unauthorized	Authentication failed	No API key or invalid key provided
402 Payment Required	Payment issue	A payment issue exists on the account
403 Forbidden	Permission denied	API key doesn't have access to the requested resource
404 Not Found	Resource not found	The resource doesn't exist
405 Method Not Allowed	Invalid HTTP method	HTTP method not supported for this endpoint
429 Too Many Requests	Rate limit exceeded	Too many requests in a short period
500 Internal Server Error	Server error	Something went wrong on our side
503 Service Unavailable	Service offline	Temporarily unavailable

Response headers

List endpoints include pagination headers:

Header	Description
`Link`	Navigation URLs following RFC 5988
`Has-More`	`true` if there are more results
`Limit`	The limit that was applied

See Pagination for details.

Rate Limits

If you exceed rate limits, you will receive a 429 Too Many Requests response with a Retry-After header.

If you need higher limits, please contact support.

Report issues

Please contact support if you are receiving unexpected errors, particularly 5xx errors.

API Responses