API Responses

Overview

The Ittybit API returns JSON encoded responses.

Each successful response includes:

• meta: containing information about the request
• data: containing the resource (or null if there was an error)
• error: containing any error messages (or null if request succeeded).
• links: containing related and page information

Success Responses

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

{
  "meta":{
    "request_id": "req_abcdefghij1234567890",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "version": "2025-01-01",
    "type": "list",
    "limit": 20,
    "total": 100,
    "page": 1,
    "pages": 5,
  },
  "data": [
    {
      "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
  ],
  "error": null,
  "links": {
    "self": "https://api.ittybit.com/files",
    "first": "https://api.ittybit.com/files?page=1",
    "prev": null,
    "next": "https://api.ittybit.com/files?page=2",
    "last": "https://api.ittybit.com/files?page=5",
  }
}

The meta.type prop will indicate whether the response is a list or an object.

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.

{
  "meta":{
    "request_id": "req_abcdefghij1234567890",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "version": "2025-01-01",
    "type": "error"
  },
  "data": null,
  "error": {
    "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."
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_abcdefgh1234",
    "parent": "https://api.ittybit.com/files",
  }
}

Error responses will contain an empty data prop ("data": null).

Meta

The meta prop will include the following properties:

• request_id string

  The unique ID for the request. If you need to contact support about an issue, including a request_id is super helpful.

• org_id string

  The ID of the org the API Key belongs to

• project_id string

  The ID of the project the API Key belongs to

• version string

  The version of the API that was used to process the request

• type enum ['object', 'list', 'error']

  The type of the data returned in the response (object or list), or error if an error occurred.

Links

Both success and error responses include a links prop containing endpoints you can use to access additional resources ¹, for example the next page in a list of results, or the parent resource of an object.

Possible links properties:

• self string

  The URL of the resource itself

• parent string

  The URL of the parent resource (usually a list endpoint)

• first string

  The URL of the first page in a list of results

• next string | null

  The URL of the next page in a list of results

• prev string | null

  The URL of the previous page in a list of results

• last string

  The URL of the last page in a list of results

Status Codes

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

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.