> ## Documentation Index > Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes > Common error codes returned by the CreatorDB API and their meanings CreatorDB communicates request status through HTTP response codes. A response in the **2xx** range means the request was successful, while a **4xx** response suggests an error caused by invalid credentials, insufficient API credits, or missing parameters. A response in the **5xx** range indicates an error on the server side, which may be temporary. If you encounter a **5xx** error, please try your request again later. If the issue persists, contact CreatorDB support for assistance. ## Error types and HTTP status codes The following table shows the different error `types` based on the status code of the HTTP response: | HTTP STATUS CODE | ERROR `TYPE` | DESCRIPTION | | ---------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `VALIDATION ERROR` | This request is invalid or a validation error occurred. Check the `details` field in the response for more information about the specific errors. | | 401 | `UNAUTHORIZED` | This request is unauthorized. This error occurs when the API key is missing or invalid. Please check the API key in the request header and make sure it is correct. | | 402 | `PAYMENT REQUIRED` | You have exhausted all plan and purchased credits. Add credits to your account or wait for your monthly plan refresh before retrying. You can check your remaining balance by calling the `GET /usage` endpoint. | | 403 | `FORBIDDEN` | This request is authenticated but the user does not have permission to access the requested resource. Check your API key permissions and ensure you are authorized to access the requested data. | | 404 | `NOT FOUND` | The requested resource could not be found. This error occurs when the specified endpoint or resource does not exist. Verify the endpoint URL and parameters in your request. | | 409 | `CONFLICT` | This request could not be completed due to a conflict with the current state of the resource. This error may occur when there are duplicate entries or conflicting data in the request. Check the request data for any conflicts and try again. | | 429 | `RATE LIMIT EXCEEDED` | Too many requests. Wait and retry your request with backoff. Note that credit exhaustion returns a `402 Payment Required` error, not a `429`. | | 500 | `INTERNAL SERVER ERROR` | An unexpected error occurred on the server. This error may occur due to temporary issues or maintenance. Please try again later. If the issue persists, contact CreatorDB support for assistance. | | 503 | `SERVICE UNAVAILABLE` | The server is currently unavailable. This error may occur due to temporary database or upstream service issues or maintenance. Please try again later. If the issue persists, contact CreatorDB support for assistance. | ## Response envelope Every CreatorDB API response follows the same JSON envelope. The fields vary slightly depending on whether the call succeeded or failed. ### Success ```json theme={null} { "data": { /* endpoint-specific payload */ }, "creditsUsed": 2, "creditsAvailable": 850, "traceId": "d052411b141435a0a47bf503598ffa0e", "timestamp": 1780241588992, "errorCode": "", "errorDescription": "", "success": true } ``` ### Error ```json theme={null} { "success": false, "error": "ValidationError", "message": "Request validation failed", "errorCode": "VALIDATION_ERROR", "traceId": "0e3562b4949d2d24effc8d089037e7b0", "timestamp": 1780242520254, "details": [ /* field-level errors, 400 only */ ] } ``` ### Field reference | Field | Present on | Notes | | :----------------------------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | **`success`** | All responses | `true` on 2xx, `false` on 4xx/5xx. | | **`data`** | Success only | Endpoint-specific payload. | | **`creditsUsed`** / **`creditsAvailable`** | Success only | Credits consumed by this call and your remaining balance. Absent on error responses. | | **`traceId`** | Most responses | Unique request ID. Include this when contacting support. | | **`timestamp`** | Most responses | Unix epoch in **milliseconds**. | | **`error`** | Error responses | Error class name (e.g. `ValidationError`, `UnauthorizedError`). Use for matching on a typed name. | | **`errorCode`** | Success (empty string) + most error responses | Stable machine-readable code (e.g. `VALIDATION_ERROR`, `UNAUTHORIZED`). Use this for programmatic branching — the table above is keyed on `errorCode`. | | **`message`** | Error responses | Human-readable error description. Some `errorCode` values have more than one possible `message` — see notes below. | | **`errorDescription`** | Success only (empty string) | Placeholder for forward compatibility. Error responses use `message` instead. | | **`details`** | 400 `VALIDATION_ERROR` only | Array of field-level validation errors describing which parameter failed and why. | ### Schema notes **`UNAUTHORIZED` covers two cases.** The `errorCode` is identical for both; use `message` to distinguish them: * `"API Key is required"` — the `api-key` header is missing or empty * `"Invalid API Key"` — the header is present but the key is not recognized **Malformed IDs and unknown IDs return different status codes.** If a `channelId`, `videoId`, `uniqueId`, or `brandId` fails format validation (wrong length, invalid characters), you get a **400 `VALIDATION_ERROR`** with a `details[]` array describing the problem. If the ID is correctly formatted but doesn't exist in the database, you get a **404** with a resource-specific `errorCode`: `NOT_FOUND` for creator and brand lookups, `SUBTITLE_VIDEO_NOT_FOUND` for subtitle lookups. If you're used to APIs that return 404 for all unknown input, expect malformed values to take the 400 path here. **404 has two distinct response shapes.** A resource-not-found 404 follows the standard error envelope — it includes `error: "NotFoundError"`, `errorCode`, `traceId`, and `timestamp`. A path-level 404 (a request to a URL that doesn't exist, like `/youtube/no-such-endpoint`) does not: `error` is the plain string `"Not Found"`, and `errorCode`, `traceId`, and `timestamp` are all absent. An `availableEndpoints` array appears in their place. Treat path-level 404s as a separate response shape.