# API Responses
[View original](https://ittybit.com/api/responses)
## Success Responses
Success responses will return either an object or a list of objects, depending on the endpoint.
```json title="success.json"
{
"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",
}
}
```
```json title="success.json"
{
"meta":{
"request_id": "req_abcdefghij1234567890",
"org_id": "org_abcdefgh1234",
"project_id": "prj_abcdefgh1234",
"version": "2025-01-01",
"type": "object",
},
"data": {
"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"
},
"error": null,
"links": {
"self": "https://api.ittybit.com/files/file_abcdefgh1234",
"parent": "https://api.ittybit.com/files",
}
}
```
The `meta.type` prop will indicate whether the response is a list or an object.
For list responses with no results, the `data` prop will be an empty array.
***
## 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.
```json title="error.json"
{
"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](/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 [^1], 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.
| 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](/support) to discuss your requirements and we will be happy to set-up custom limits for your project.
***
## Report issues
Please do [contact support](/support) if you are receiving unexpected errors, particularly if you are receiving `5xx` errors.
We'll work with you to solve the problem asap.
***
[^1]: We have consciously chosen not to include a complete hypermedia implementation. The limited extra functionality is not worth increased response size for every request. Take away our RESTful badge if you want, we don't care. 😊