> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/api-and-mcp-concepts/error-handling.md).

# Errors and retries

Diagnose authentication, validation, media, and async failures without blind retries or duplicate writes.

Read the returned error before changing the request. For REST requests, record the HTTP status and response body. For MCP, inspect the tool result and its `isError` flag. A request accepted by Blotato still needs its workflow's completion check.

For customer support, use [Diagnose and answer](/start-with-an-ai-agent/agent-triage.md) to preserve the client, failing stage, previous attempts, and human corrections. Do not repeat a setup question already answered in the conversation.

For missing, delayed, or duplicate posts, follow [Find a post's outcome before retrying](/start-with-an-ai-agent/publishing-status.md). An HTTP status or an inaccessible platform URL alone does not establish the underlying cause.

| Error or symptom                           | Next step                                                                                                                              |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `401`, invalid API key, or invalid session | Follow [authentication checks](/api-and-mcp-concepts/authentication.md)                                                                |
| Subscription-related `403`                 | Check [Billing](https://my.blotato.com/settings/billing)                                                                               |
| `404`                                      | Re-fetch the record and verify the ID type and account                                                                                 |
| Validation error, often `422`              | Correct the named field using the endpoint schema                                                                                      |
| `429`                                      | Wait for the retry interval if provided, then reduce request frequency                                                                 |
| Network error or `5xx` on a read           | Retry with a delay and a bounded attempt count                                                                                         |
| Network error after a create request       | Check existing work before submitting again                                                                                            |
| Post status `failed`                       | Read `errorMessage` and the [platform requirements](/platform-publishing/platforms.md)                                                 |
| Visual response contains `item.error`      | Stop polling and explain the generation error                                                                                          |
| Empty analytics or inbox result            | Check the feature's [sync timing and supported platforms](/web-app-features/analytics.md) or [inbox setup](/web-app-features/inbox.md) |
| Media fetch or conversion failure          | Follow the [media checklist](/api-and-mcp-concepts/media-uploads-and-conversion.md)                                                    |

## Inspect a failed request

1. Open the [Logs](https://my.blotato.com/logs).
2. Select the request.
3. Read its payload, response, and error message.
4. Correct the cause before resubmitting.

For n8n requests, the dashboard's FIX MY AUTOMATION action helps repair the workflow. See the [n8n walkthrough](/integrations-and-automation-templates/n8n/faqs.md#first-step-click-fix-my-automation-in-the-api-dashboard-n8n-only). This action is specific to n8n.

## Retry without duplicating work

1. Save every submission or creation ID returned by a successful create request.
2. If a status call fails, retry the status call with the saved ID.
3. If creation timed out without an ID, inspect the dashboard and existing posts or schedules before creating another item.
4. For a failed post, correct the error before a new submission. An unchanged retry often fails for the same reason.
5. Set an attempt or elapsed-time limit in your automation. Report unfinished work and its ID when the limit is reached.

Blotato does not expose a documented client-supplied idempotency header for create-post requests. Internal duplicate detection is not a guarantee for arbitrary changed payloads, times, or retries. Retain the submission ID, inspect existing work, and do not invent an idempotency header.

See [Error reference](/support/errors.md), [API FAQs](/start-with-an-ai-agent/faqs.md), [MCP FAQs](/start-with-an-ai-agent/mcp/faqs.md), and [Get support](/support/get-support.md) for specific cases.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.blotato.com/api-and-mcp-concepts/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.