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 (support@creatordb.app) for assistance.

Error types and HTTP status codes

The following table shows the different errors types based on the status code of the HTTP response:

HTTP STATUS CODE	ERROR `TYPE`	ERROR `CODE`	DESCRIPTION
400	`VALIDATION ERROR`	`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`	`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`	`INSUFFICIENT_CREDITS`, `KEY_SPEND_THRESHOLD_EXCEEDED`	`INSUFFICIENT_CREDITS`: you have exhausted all plan and purchased credits. Add credits to your account or wait for your monthly plan refresh before retrying. `KEY_SPEND_THRESHOLD_EXCEEDED`: the request would exceed the spend limit set on this key. Raise the limit for that key. You can check your remaining balance by calling the `GET /usage` endpoint.
403	`FORBIDDEN`	`FORBIDDEN`, `FRACTIONAL_CALLS_NOT_ENABLED`, `SUBMIT_CREATORS_DISABLED`, `SPONSOR_SUBMIT_DISABLED`	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`	`NOT_FOUND`, `SUBTITLE_VIDEO_NOT_FOUND`, `SUBTITLE_VSSID_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.
429	`RATE LIMIT EXCEEDED`	`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`	`INTERNAL_ERROR`, `NLS_SQL_EXECUTION_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`	`SERVICE_UNAVAILABLE`, `STORAGE_ERROR`	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.

Fractional call errors

Requests with a fields parameter have specific failure modes. Unless specified otherwise, all return 400 VALIDATION_ERROR, with details in details[].

Fractional calls not enabled on the key

The fields parameter requires fractional calls to be enabled on your API key. If it is not enabled, any request including fields returns 403 FORBIDDEN with errorCode: "FRACTIONAL_CALLS_NOT_ENABLED". Requests without fields are unaffected and return full responses at the full-bundle price. Contact your account manager to enable fractional calls.

Incorrect `fields` shape for the endpoint

The fields parameter requires a different data structure depending on the endpoint. Passing an invalid structure returns a 400 VALIDATION_ERROR. This is the most common fractional call error.

Endpoint type	Expected shape	Rejected shape
`profile`, `performance`, `audience`, `contact`	Array of field names	Object
`content-detail`, `sponsorship`	Object mapping an array name to a count	Array
`performance-history`	Does not accept `fields` at all	`fields` in any shape

Per-item endpoints do not accept the legacy :N string-array form. For example, passing ["recentVideos:5"] or ["sponsorList:5"] returns a 400 error. Use { "recentVideos": 5 } instead. For performance-history endpoints, pricing is determined solely by the requested pastDayRange. Sending fields in any shape returns a 400 error.

Unknown or unselectable field names

Unlisted fields: Requesting a field name not on the endpoint’s allowlist returns a 400 VALIDATION_ERROR.
Undeployed fields: Fields that are not yet deployed return a 400, even when they appear in reference documentation.
Sub-fields: Sub-fields are not individually selectable. For example, requesting sponsorList[].brandName or sponsoredVideosPerformance.likes.avg returns a 400. The smallest unit you can select is a whole field or array on the allowlist. To get a sub-field, request its parent block.

Duplicate field names do not trigger an error. They are silently deduplicated, then returned and billed as a single field.

Platform-prefixed enrichment keys on search endpoints

For /{platform}/search, fields keys must use bare endpoint names. Do not prefix the key with a platform name, as the platform is already implied by the URL.

// Correct
{ "fields": { "profile": ["country"] } }

// 400 VALIDATION_ERROR - any key containing a slash is rejected
{ "fields": { "youtube/profile": ["country"] } }

Invalid item counts on per-item endpoints

The value mapped to an array name must be a non-negative integer. Passing a negative number (-5), a non-integer (1.5), or a non-numeric value returns a 400 VALIDATION_ERROR. Passing 0 and null is valid. These return zero items for that array and cost 0 credits. Requesting large item counts is also safe: costs are calculated based only on the items actually returned and are capped at the endpoint’s full-bundle price. You will not be overcharged if you request more items than exist.

Empty `fields` is not an error

Sending fields: [] on a field-list endpoint or fields: {} on a per-item endpoint returns the full response at the full-bundle price, exactly as if fields were omitted. Neither shape triggers a validation error, and neither returns an empty response.

Insufficient credits

If the estimated cost exceeds your remaining credits, the call returns 402 with errorCode: "INSUFFICIENT_CREDITS" and no partial data. The details object reports what the call required against what is available. A per-key spend limit produces the same 402 status with errorCode: "KEY_SPEND_THRESHOLD_EXCEEDED". Branch on errorCode, not on the status alone.

Response envelope

Every CreatorDB API response follows the same JSON envelope, with a single exception described below. 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": "channelId", "message": "Invalid YouTube channel ID format" }
  ]
}

Field reference

Field	Present on	Notes
`success`	All responses	`true` for `2xx`; `false` for `4xx/5xx`.
`data`	Success only	Endpoint-specific payload.
`creditsUsed` / `creditsAvailable`	Success only	Credits consumed by the request and your remaining balance. Omitted on errors.
`traceId`	Most responses	Unique request ID. Include this when contacting CreatorDB support.
`timestamp`	Most responses	Unix epoch timestamp in milliseconds.
`error`	Error responses	Runtime class name (e.g. `ValidationError`, `UnauthorizedError`). Use for matching on a typed name. For programmatic branching, use `errorCode`.
`errorCode`	Success (empty string) + most error responses	Stable machine-readable code (e.g. `VALIDATION_ERROR`, `UNAUTHORIZED`). Use this for programmatic branching. The Error types and HTTP status codes table is keyed on it.
`message`	Error responses	Human-readable error description. A single `errorCode` may have more than one possible `message` (For details, see notes below).
`errorDescription`	Success only (empty string)	Placeholder for forward compatibility. Error responses use `message` instead.
`details`	`400` and `402` errors	Two shapes. Parse by status rather than assuming an array. On a 400, an array of `{ field, message }` objects naming which parameter failed and why. On a 402, an object reporting the credits required against your available balance.

Schema notes

UNAUTHORIZED covers two cases. Both cases share the same errorCode. Use message to distinguish them:

"API Key is required": The api-key header is missing or empty.
"Invalid API Key": The api-key header is present but the key is not recognized.

Malformed IDs and unknown IDs return different status codes.

Malformed format (400): If a channelId, videoId, or uniqueId fails format validation (invalid characters or length), it returns a 400 VALIDATION_ERROR with a details[] array describing the problem.
Missing resource (404): If the ID is formatted correctly but does not exist in the database, it returns a 404 with a resource-specific errorCode (NOT_FOUND for creator and brand lookups, SUBTITLE_VIDEO_NOT_FOUND for subtitle lookups).

If you are used to APIs that return 404 for all unknown input, expect malformed values to take the 400 path here. Sponsor brandId is validated on characters only. Unlike the creator IDs above, brandId is checked for illegal characters (anything outside letters, digits, ., _, and -) and nothing else. There is no length limit and no domain-shape check, so a value like notadomain or a 300-character string passes validation, reaches the database, and returns 404 NOT_FOUND rather than a 400. Reserve your 400-handling solely for illegal characters here. One parameter can produce several details[] entries. On a 400, details is one-to-many per field, not one message per field. An invalid videoId length trips both the length check and the format check, returning two entries for the same field. An empty sponsor brandId returns both a required-value failure and a character failure. Iterate the whole details[] array so your client does not drop the rest. 404 has two distinct response shapes.

Resource 404: Follows the standard error envelope (error: "NotFoundError", errorCode, traceId, timestamp).
Path 404: A request to a non-existent URL (e.g. /youtube/no-such-endpoint). It bypasses the standard envelope: error is the plain string "Not Found", errorCode/traceId/timestamp are omitted, and an availableEndpoints array appears in their place.

500 messages are deliberately generic. On the unexpected-error path the underlying message is replaced with "An unexpected error occurred". There is no detail to parse. Use traceId when you contact CreatorDB support.

One endpoint does not return the envelope

POST /youtube/subtitles/download streams the subtitle file as an attachment. It returns no data, creditsUsed, creditsAvailable, traceId, or success.

Aspect	Value
`Content-Type`	`application/json`
`Content-Disposition`	`attachment; filename="{videoId}-{vssId}.json"`
`Transfer-Encoding`	`chunked`

Errors raised before streaming begins do use the standard envelope. That covers pre-flight validation (400) and rate limiting or credit exhaustion (429). An error that occurs mid-stream cannot be reported in the body, so a failed download can leave partial data. Validate the file you received rather than assuming a 200 means a complete track. Every other endpoint in the API returns the standard envelope.

Additional error handling notes

Retry hints are omitted from headers. The API does not send Retry-After, X-RateLimit-Remaining, or similar headers on 429 or 402 responses. Use GET /usage to check your remaining balance, and implement custom backoff logic. error maps to multiple errorCode. The error field contains the runtime class name, and one class can represent multiple error codes. For example, NotFoundError covers NOT_FOUND, SUBTITLE_VIDEO_NOT_FOUND, and SUBTITLE_VSSID_NOT_FOUND. Always branch your code on errorCode. Error responses are free. 4xx and 5xx error responses do not consume credits.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Error types and HTTP status codes

Fractional call errors

Fractional calls not enabled on the key

Incorrect `fields` shape for the endpoint

Unknown or unselectable field names

Platform-prefixed enrichment keys on search endpoints

Invalid item counts on per-item endpoints

Empty `fields` is not an error

Insufficient credits

Response envelope

Success

Error

Field reference

Schema notes

One endpoint does not return the envelope

Additional error handling notes

​Error types and HTTP status codes

​Fractional call errors

​Fractional calls not enabled on the key

​Incorrect fields shape for the endpoint

​Unknown or unselectable field names

​Platform-prefixed enrichment keys on search endpoints

​Invalid item counts on per-item endpoints

​Empty fields is not an error

​Insufficient credits

​Response envelope

​Success

​Error

​Field reference

​Schema notes

​One endpoint does not return the envelope

​Additional error handling notes

Error types and HTTP status codes

Fractional call errors

Fractional calls not enabled on the key

Incorrect `fields` shape for the endpoint

Unknown or unselectable field names

Platform-prefixed enrichment keys on search endpoints

Invalid item counts on per-item endpoints

Empty `fields` is not an error

Insufficient credits

Response envelope

Success

Error

Field reference

Schema notes

One endpoint does not return the envelope

Additional error handling notes