Error Codes

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.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Error types and HTTP status codes

Response envelope

Success

Error

Field reference

Schema notes

​Error types and HTTP status codes

​Response envelope

​Success

​Error

​Field reference

​Schema notes

Error types and HTTP status codes

Response envelope

Success

Error

Field reference

Schema notes