Errors

The TokPortal API uses a consistent error format across all endpoints. Errors are returned as JSON with an error object.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the problem.",
    "details": {}
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code. Use this for programmatic handling.
`message`	`string`	Human-readable description. May change — do not match against this.
`details`	`object`	Optional. Additional context (e.g., which field failed validation, credit breakdown).

Every response also includes a correlation header:

X-TokPortal-Request-ID: req_...

Generated SDKs expose this value on structured API errors as requestId, request_id, or RequestID. Include it when contacting support about a failed request.

Error Code Reference

Authentication Errors

Code	HTTP	Description
`AUTH_MISSING_KEY`	401	No `X-API-Key` header was provided in the request.
`AUTH_INVALID_KEY`	401	The API key does not match any account.
`AUTH_REVOKED_KEY`	401	The API key has been revoked. Generate a new key from the developer dashboard.

Rate Limiting

Code	HTTP	Description
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Wait and retry. See Rate Limits.

429 responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Billing

Code	HTTP	Description
`INSUFFICIENT_CREDITS`	402	Not enough credits. Response includes `required`, `available`, `missing`, and `breakdown` in `details`.

Bundle Errors

Code	HTTP	Description
`BUNDLE_NOT_FOUND`	404	The specified bundle does not exist.
`BUNDLE_NOT_OWNED`	403	The bundle belongs to another account.
`BUNDLE_INVALID_STATUS`	409	The bundle is not in a valid status for this operation (e.g., trying to configure a published bundle).
`BUNDLE_ALREADY_PUBLISHED`	409	The bundle has already been published and cannot be modified.

Account Errors

Code	HTTP	Description
`ACCOUNT_NOT_FOUND`	404	The specified account does not exist.
`ACCOUNT_INVALID_STATUS`	409	The account is not in a valid status for this operation.
`ACCOUNT_NOT_CONFIGURED`	409	The account must be configured before this operation can proceed.

Saved Account Errors

Code	HTTP	Description
`SAVED_ACCOUNT_NOT_FOUND`	404	The specified saved account does not exist.
`SAVED_ACCOUNT_NOT_OWNED`	403	The saved account belongs to another user.

Video Errors

Code	HTTP	Description
`VIDEO_NOT_FOUND`	404	The specified video does not exist.
`VIDEO_INVALID_STATUS`	409	The video is not in a valid status for this operation.
`VIDEO_POSITION_OUT_OF_RANGE`	400	The video position exceeds the available slots.
`VIDEO_NO_DOWNLOAD_ISSUE`	409	The video does not have a download issue to fix.

Account Edit Request Errors

Code	HTTP	Description
`EDIT_REQUEST_NO_CM`	400	No manager assigned to this account.
`EDIT_REQUEST_ALREADY_EXISTS`	409	Another edit request is already in progress.
`EDIT_REQUEST_NO_ACTIVE_ORDER`	400	No active order for this account.

Validation Errors

Code	HTTP	Description
`INVALID_COUNTRY`	400	The country code is not supported.
`INVALID_PLATFORM`	400	The platform is not supported. Valid values: `tiktok`, `instagram`, `youtube`.
`INVALID_VIDEO_TYPE`	400	The video type is not valid for the target platform.
`INVALID_DATE`	400	The date is malformed or out of the allowed range.
`INVALID_FIELD`	400	A field value is invalid (details specify which field and why).
`INVALID_BODY`	400	The request body is malformed or not valid JSON.
`MISSING_FIELD`	400	A required field is missing from the request body.

Configuration Errors

Code	HTTP	Description
`EDIT_SLOTS_EXCEEDED`	400	The number of edit slots exceeds the allowed limit.
`WARMING_CONFLICT`	400	Conflicting warming options were specified.
`DEEP_WARMING_PLATFORM`	400	Deep warming is only available for Instagram accounts.
`VIDEOS_ONLY_REQUIRES_ACCOUNT`	400	A videos-only bundle requires an existing saved account.
`ACCOUNT_ID_NOT_ALLOWED`	400	The `account_id` field was passed with a `bundle_type` other than `videos_only`. To add videos to an existing saved account, set `bundle_type` to `videos_only` (this also skips the account-creation credit charge).

Analytics Errors

Code	HTTP	Description
`ANALYTICS_COOLDOWN`	429	Analytics were recently refreshed. Wait before requesting again.
`ANALYTICS_QUOTA_EXCEEDED`	429	Analytics refresh quota has been exceeded for this period.
`ANALYTICS_NOT_FOUND`	404	No analytics data is available for this account.

Verification Errors

Code	HTTP	Description
`VERIFICATION_CODE_NOT_FOUND`	404	No pending verification code was found for this account.

CSV Errors

Code	HTTP	Description
`CSV_PARSE_ERROR`	400	The CSV file could not be parsed. Check formatting and encoding.
`CSV_VALIDATION_ERROR`	400	The CSV content failed validation. `details` includes row-level errors.

Server Errors

Code	HTTP	Description
`UPLOAD_FAILED`	500	A file upload failed. Retry the request.
`INTERNAL_ERROR`	500	An unexpected server error occurred. If this persists, contact support.

Handling Errors in Code

const response = await fetch("https://app.tokportal.com/api/ext/bundles", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TOKPORTAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(bundleConfig),
});

const result = await response.json();

if (result.error) {
  switch (result.error.code) {
    case "INSUFFICIENT_CREDITS":
      console.error(
        `Need ${result.error.details.missing} more credits.`
      );
      break;
    case "AUTH_INVALID_KEY":
      console.error("Invalid API key. Check your configuration.");
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Wait and retry
      await new Promise((r) => setTimeout(r, 5000));
      break;
    default:
      console.error(`API error: ${result.error.message}`);
  }
}