> 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

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.

| 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 [API Dashboard](https://my.blotato.com/api-dashboard).
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 document an idempotency header for create-post requests. Do not invent one or assume repeated requests collapse into a single post.

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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.