Errors

Every way a Native tool can fail comes with a code. This page lists the codes a partner backend can meet, and what to do about each. Branch on the code. Never parse the message.

Native does not retry a failed publish on its own. A destination that failed stays failed until you act.

• The tool refused the call. The result has isError: true and carries the error envelope.
• Part of the call failed. Some tools succeed as a whole and report failures per destination or per post. See failures inside a result.
• The request never reached a tool. A token problem or the edge rate limit answers with an HTTP status and no envelope. See errors outside the envelope.
• An argument broke the input schema. The MCP SDK rejects it before the tool runs, with its own validation error instead of the envelope. Treat that as a bug in your call.

When a tool refuses a call, the result has isError: true, and structuredContent is { "data": <envelope> }. content[0].text holds the same envelope as a JSON string.

{
  "ok": false,
  "error": {
    "code": "schedule_preflight_failed",
    "message": "A sentence Native wrote for people",
    "retryable": false,
    "blockedDestinations": [
      {
        "platform": "INSTAGRAM",
        "code": "caption_too_long",
        "characterCount": 2410,
        "characterLimit": 2200
      }
    ]
  }
}

retryable answers one question: could the same call, sent again unchanged, succeed? It does not say the call did nothing. After a timeout, read the current state before you retry. See retrying.

Some codes carry extra fields beside code, message and retryable. They sit on the same error object. Each one is named with the codes that use it. Destination names in these fields are uppercase Platform enum names, such as INSTAGRAM.

These are the codes a whole call can fail with, grouped by what they are about. The retryable column is the value the envelope carries.

One refusal has no code of its own in the gateway today. When update_post tries to remove a destination that the provider is holding, the refusal arrives as upstream_409. Withdraw that destination with unschedule_platform first.

New, in development: this refusal arrives as platform_scheduled, with retryable: false. The fix is the same: withdraw the destination with unschedule_platform, then remove it.

The approval gate runs before schedule_post and publish_post_now, and refuses the whole call. reschedule_posts runs it for each entry and reports a refusal in that entry’s moves[].error. post_content_changed comes from approve_post and reject_post. Approval explains the content digest behind these codes.

Scheduling runs per destination underneath, so schedule_failed can leave some destinations booked. scheduledDestinations lists them, and refusedDestinations lists the ones that refused, each with a code per destination.

The envelope’s retryable is false when any refusing destination has media_invalid, channel_not_connected, channel_needs_reauth or content_rejected. It is true otherwise. A retry books only the destinations still outstanding.

One exception: when the error carries neither refusedDestinations nor scheduledDestinations, Native could not say which destination refused, and retryable is false. Read get_post_status for the reason before you change anything.

{
  "ok": false,
  "error": {
    "code": "schedule_failed",
    "message": "A sentence Native wrote for people",
    "retryable": true,
    "refusedDestinations": [{ "platform": "INSTAGRAM", "code": "provider_unavailable" }],
    "scheduledDestinations": ["FACEBOOK"]
  }
}

Here Facebook is booked and Instagram was refused because the provider was unavailable. Call schedule_post again unchanged, and it books only Instagram.

Some tools succeed as a whole and report what failed inside the result. Each failure there carries a code and a message, and all but the dry-run entries carry retryable too.

• publish_post_now: publishResults[].reason, one per destination. Only published means a destination is live.
• reschedule_posts: moves[].error, one per entry, with the same codes as schedule_post. The other entries still ran.
• get_post_batch_status: items[].error, one per post. Item codes are usage_limit_exceeded, ai_generation_failed, platform_not_connected, platform_not_supported, reddit_options_required, media_required, bad_request and internal_error.
• get_post_status: platformResults[].error, one per destination.
• get_generation_job: error, when a render failed.
• New, in development: schedule_post and publish_post_now with dryRun: true return blocked[], what would stop each destination, with platform, code and message. Its codes include the pre-flight codes, channel_not_connected and channel_needs_reauth, and for publish_post_now the skip reasons too. Other codes can appear, such as brand_inactive.

These codes describe why one destination failed. They appear in platformResults[].error.code, publishResults[].reason.code and refusedDestinations[].code.

Before schedule_post contacts any platform, Native checks each destination against that platform’s rules. A destination that fails a rule appears in blockedDestinations[] with one of these codes.

Fix every destination named, or leave those destinations out with platforms, before you call again. Unchanged, the call fails the same way.

publish_post_now answers with publishResults[], one per destination. A destination that did not publish carries a reason:

When an image render fails, get_generation_job reports status: "failed" and an error with one of these codes. To retry a failed render, call regenerate_post_image again. Never do that while the job is still running.

Two flows report failure outside a tool result: a profile build that runs in the background, and an account connection that ends in the client’s browser. Both are new and in development.

New, in development: when a create_profile build fails, get_profile reports onboarding.status: "failed" and a code in onboarding.error: website_unreachable, analysis_failed, enrichment_failed, build_not_queued or build_interrupted. Treat the list as open: more codes can appear. create_profile answers status: "failed" only when it could not start the build, in practice with build_not_queued.

To retry a failed build, call create_profile again with the same externalId. The build restarts where it stopped and the call answers building, so read the code from get_profile before you retry.

New, in development: when create_profile refuses the website with invalid_website_url, nothing is created and websiteRefusal says why:

New, in development: a headless connect link sends the browser back to your returnUrl with status=failed and an error code, for example oauth_denied, link_expired, account_in_another_workspace or connection_failed. Mint a fresh link to retry. Do not poll: a failed connect does not recover on its own.

These answers come back as an HTTP status before any tool runs, so they carry no envelope.

An argument that breaks a tool’s input schema is rejected by the MCP SDK before the tool runs. You get the SDK’s validation error, not the envelope. Check your call against the inputSchema that tools/list returns.

• Respect retryable. Never send a call again after retryable: false without changing something first.
• After a timeout or a dropped connection on a write, read the current state before you retry, with get_post_status, get_post_batch_status or view_post. A lost response does not prove that nothing changed.
• publish_post_now is safe to call again. It retries only the destinations that failed and never dispatches a published one again. The skip reasons stuck_at_provider and story_partially_published need Native support or a new post, not a retry.
• A partly refused reschedule_posts call is not untouched: the other entries ran. Do not resend the whole list.
• Never call regenerate_post_image again to retry a render that is still running. Poll its job with get_generation_job.
• Back off exponentially, with jitter, on errors that are retryable. Stop on errors that are not.

For each tool call, the gateway attaches an Idempotency-Key to every write it makes to Native, and Native replays the stored result for a repeated key. The transport keeps no state between calls, though, so each tool call gets a fresh random part in its key. If you send the same tool call again, it is a new attempt, and Native does not deduplicate it.

Caller-supplied idempotency keys are planned, not available. Until then, check the current state before you retry any write that creates or publishes something: create_posts, publish_post_now and schedule_post.

New, in development: create_profile is idempotent on its own terms. A repeat with the same externalId answers with the profile the first call made, with created: false.

New codes can appear at any time for new failure cases. Treat a code you do not recognise as its retryable flag says.

A call with the official MCP SDK client, branching on the code:

const result = await client.callTool(
  {
    name: "schedule_post",
    arguments: { id: postId, scheduledAt: "2026-11-02T09:00:00+01:00" },
  },
  undefined,
  { timeout: 150_000 },
);

const data = (result.structuredContent as { data: any } | undefined)?.data;

if (result.isError) {
  const error = data.error as {
    code: string;
    message: string;
    retryable: boolean;
    blockedDestinations?: { platform: string; code: string }[];
  };

  switch (error.code) {
    case "schedule_preflight_failed":
      // Nothing was booked. Fix every destination it names, then call again.
      for (const blocked of error.blockedDestinations ?? []) {
        console.warn(blocked.platform, blocked.code);
      }
      break;
    case "approval_stale":
      // Read the post again with view_post and have it reviewed again.
      break;
    default:
      if (error.retryable) {
        // Read the current state first, then retry with backoff.
      } else {
        // Change something before calling again. Never parse error.message.
      }
  }
}