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": {}
  }
}

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

Rate Limiting

API-key throttling responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Bundle-capacity cooldowns do not expose capacity counters.

Idempotency

For a network timeout where no response was received, also retry the exact same request with the same key. Reusing a key with a changed body is always an integration error. Completed responses replay for 24 hours after completion. Uncertain processing claims never expire automatically into a second execution; they remain fail-closed until TokPortal support/operator reconciles the request, resource, and financial logs. Include the X-TokPortal-Request-ID, request timestamp, method, path, idempotency key, and a non-secret correlation reference when asking for reconciliation.

Billing

Bundle Errors

Account Errors

Saved Account Errors

TokPortal Coverage

Credential Reveal and Account Owning Fee

Video Errors

Account Edit Request Errors

Validation Errors

Configuration Errors

Analytics Errors

Verification Errors

CSV Errors

Server Errors

Unknown fields

A field TokPortal does not recognise used to be dropped during validation and the request succeeded anyway. On a full-replace write that was quietly destructive: a body sending biograhpy instead of biography was accepted with a 200, and because the endpoint replaces the whole record, the stored biography was wiped to null.

Unrecognised fields are now reported, and on the endpoints where dropping them destroys data they are refused:

The error names the fields, suggests the closest valid one, and lists what the endpoint does accept:

{
  "error": {
    "code": "UNKNOWN_FIELD",
    "message": "The request body contains fields TokPortal does not recognise. On this endpoint a write is a FULL REPLACE, so a misspelled field is not merely ignored — it erases the value it was meant to set. Check \"details.unknown_fields\" for the exact names and \"details.did_you_mean\" for the closest valid field. Endpoints that only ignore unknown fields report them in \"meta.ignored_fields\" instead of failing.",
    "details": {
      "unknown_fields": ["biograhpy"],
      "did_you_mean": { "biograhpy": "biography" },
      "accepted_fields": ["username", "display_name", "biography", "profile_picture_url", "link_in_bio"]
    }
  }
}

The check descends into arrays, so a typo inside one item of a batch body is caught too.

When the field is real but sent to the wrong place

A spelling guess is the wrong answer for a field that exists, is spelled correctly, and is simply not settable on that endpoint. Those cases answer 400 UNKNOWN_FIELD with details.hints, and the message is the fix:

{
  "error": {
    "code": "UNKNOWN_FIELD",
    "message": "auto_publish is a top-level field on this endpoint and applies to every video in the call — move it out of videos[]. It cannot be set per item: there is one publish attempt per call, not one per video.",
    "details": {
      "unknown_fields": ["videos[0].auto_publish"],
      "hints": {
        "videos[0].auto_publish": "auto_publish is a top-level field on this endpoint and applies to every video in the call — move it out of videos[]. It cannot be set per item: there is one publish attempt per call, not one per video."
      },
      "accepted_fields": ["videos", "auto_publish"]
    }
  }
}

WARNING: These fire for every caller, not only MCP Unlike the did-you-mean refusal below, the hints refusals ignore API_STRICT_UNKNOWN_FIELDS. Both fields used to be dropped in silence, so the call was answered 200 and the thing it asked for never happened — a publishing window nobody chose, a batch that was never published. A 400 naming the fix is strictly better than that. Two production REST integrations were sending target_publish_end_date on configure when this shipped.

INFO: Who gets the 400 today

The refusal is gated by the API_STRICT_UNKNOWN_FIELDS server setting, currently mcp:

• MCP callers get the 400 UNKNOWN_FIELD.
• REST callers run as before and get the names back in meta.ignored_fields on the response.

The gate exists because request bodies are not stored, so there is no way to know in advance which live integrations would start failing. meta.ignored_fields is the telemetry that will decide when the refusal is extended to every caller — treat anything appearing there as a bug in your integration, not as a supported way to send extra data.

Two related cases are reported rather than refused:

• A link_in_bio on a non-Instagram bundle is accepted, stored as null, and named in the response's _warnings array.
• Platform-inapplicable video fields (TikTok-only fields on an Instagram slot, and vice versa) come back as ignored_fields.

Read meta.ignored_fields and _warnings, not just the status code.

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_limited":
    case "RATE_LIMIT_EXCEEDED": // Legacy code
      // Wait and retry
      await new Promise((r) => setTimeout(r, 5000));
      break;
    default:
      console.error(`API error: ${result.error.message}`);
  }
}