# API Responses [View original](https://ittybit.cloud/api/responses) ## Success Responses Success responses will return either an object or an array of objects, depending on the endpoint. ```json // 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 ] ``` ```json // 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. ```json // 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](/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.