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
{
"data": { /* endpoint-specific payload */ },
"creditsUsed": 2,
"creditsAvailable": 850,
"traceId": "d052411b141435a0a47bf503598ffa0e",
"timestamp": 1780241588992,
"errorCode": "",
"errorDescription": "",
"success": true
}
Error
{
"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. Last modified on June 4, 2026
