Ittybit

Overview

The Ittybit API returns JSON encoded responses.

Each successful response includes either an:

object: most endpoints return an object containing all the data for a specific resource
array: list endpoints return an array of objects, with the max length based on your pagination options
error: if something goes wrong we'll return an error (object) containing a message

Success Responses

Success responses will return either an object or an array of objects, depending on the endpoint.

// GET /files
[
  {
    "id": "file_abcdefgh1234",
    "kind": "image",
    "url": "https://you.ittybit.net/file_abcdefgh1234",
    // ... other props
  },
  {
    "id": "file_abcdefgh5678",
    "kind": "video",
    "url": "https://you.ittybit.net/file_abcdefgh5678",
    // ... other props
  },
  // ... other files
]

// GET /files/{id}
{
  "id": "file_abcdefgh1234",
  "kind": "image",
  "type": "image/png",
  "width": 1280,
  "height": 720,
  "filesize": 123456,
  "url": "https://you.ittybit.net/file_abcdefgh1234",
  "metadata": {},
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-01-01T00:00:00Z"
}

For list responses with no results, we will return an empty array ([]), not null nor undefined. We also don't throw an error if the params are valid but there's just no results.

Error Responses

If the Ittybit API encounters an error, it will include an error object in the response.

The error object will contain a human-readable message explaining the issue.

// 404 Not Found
{
  "message": "The requested file was not found. Please check the URL, that the ID is correct, and that you have used a valid API Key for the relevant project."
}

Error responses will have a 4XX or 5XX status code. See below.

Status Codes

The Ittybit API uses standard HTTP response codes to indicate the success or failure of an API request.

Status Code	Description	When You'll See It
200 OK	Request succeeded	The most common success response, returned when a request completes successfully
201 Created	Resource created	Returned when a new resource is successfully created via a POST request
202 Accepted	Request accepted	The request was accepted for processing, but the processing may not have completed yet
400 Bad Request	Invalid request	The request was malformed or missing required parameters
401 Unauthorized	Authentication failed	No API key was provided or the provided key was invalid
402 Payment Required	Payment issue	Your account has billing issues or has reached its quota limit
403 Forbidden	Permission denied	Your API key doesn't have permission to access the requested resource
404 Not Found	Resource not found	The requested resource doesn't exist or was deleted
405 Method Not Allowed	Invalid HTTP method	The HTTP method used is not supported for this endpoint
429 Too Many Requests	Rate limit exceeded	You've exceeded the allowed number of requests per time period
500 Internal Server Error	Server error	Something went wrong on our servers (we're automatically notified)
503 Service Unavailable	Service offline	The API is temporarily unavailable, usually due to maintenance

In general:

codes in the 2xx range indicate success
codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, a request was not authorised, etc). The error prop will contain a message explaining the issue.
codes in the 5xx range indicate there is an error with Ittybit's service

Rate Limits

The Ittybit API has rate limits in place to ensure fair usage and to protect the service from abuse.

If you exceed the rate limits, you will receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how many seconds you should wait before making another request.

If you are concerned that you might exceed the rate limits, please contact support to discuss your requirements and we will be happy to set-up custom limits for your project.

Report issues

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

We'll work with you to solve the problem asap.

API Responses