Errors

Every API error code with its HTTP status, cause and what to do. Meta errors never arrive raw; each one becomes a stable code from this list.

Every error arrives in the same envelope. The code is stable and is what your code should branch on; the message is for humans, written in Portuguese, and may change.

Envelope

{ "statusCode": 400, "code": "MEDIA_INVALID", "message": "imagem acima de 8 MB", "details": { "reason": "too_large" } }

details is optional and carries the context that helps you act: the accountId that needs reconnecting, the reason of a rejected image, the account's quota.

Authentication and access

Code	HTTP	Cause	What to do
`UNAUTHORIZED`	401	Key missing, invalid, revoked or expired; Bearer and key together; invalid Bearer.	Check the header. Create another key if the current one was revoked.
`FORBIDDEN`	403	The project or organization does not belong to the token's user.	Dashboard mode only. Check `x-project-id`.
`PROJECT_REQUIRED`	400	Bearer mode without `x-project-id` on a resource route.	Dashboard mode only.
`RATE_LIMIT_KEY`	429	Request limit of the credential exceeded.	Wait for `x-ratelimit-reset`. See Limits.
`PERMISSION_REQUIRED`	403	The account was connected without the permission the route requires (`details.scope`).	If the feature is already available, reconnect the account. Features awaiting Meta's approval are listed in What does not exist yet.

Request

Code	HTTP	Cause	What to do
`VALIDATION_ERROR`	400	Missing field, wrong type, out of range, `scheduledFor` outside the window, unknown `mediaId`.	The `message` names the field (`scheduledFor: …`). Fix and resend.
`NOT_FOUND`	404	Post, account, profile or key that does not exist in this project.	Check the id. A resource from another project also answers 404.

Account connection

Code	HTTP	Cause	What to do
`PLATFORM_NOT_AVAILABLE`	403	Platform other than `instagram`.	See the Roadmap.
`STATE_INVALID`	400	The OAuth return `state` is missing, tampered with or older than 10 minutes.	Start the connection again.
`AUTHORIZATION_DENIED`	400	The user denied authorization on Instagram.	Explain why it is needed and offer to retry.
`ACCOUNT_NOT_BUSINESS`	400	Personal account.	The user switches to a professional account in Instagram's settings and connects again.
`TOKEN_INVALID`	409	Token expired or revoked (password changed, app removed). On `POST /v1/posts`, the target account needs reconnecting.	Send the user to connect the account again; the existing connection is updated.
`ACCOUNT_RESTRICTED`	409	Meta restricted the account.	Only the account owner can resolve it, on Instagram.
`ACCOUNT_IN_USE`	409	The Instagram account is already connected to another profile in this project. The connection is refused and the existing account is left untouched, on its original profile.	Disconnect the account from its current profile (`DELETE /v1/connect/integrations/:id`) before connecting it to another.

Publishing

Code	HTTP	Cause	What to do
`RATE_LIMIT_ACCOUNT`	409	The account exhausted Meta's publishing quota (100 per 24 h). `details` carries `quotaUsage` and `quotaTotal`.	Schedule for later or use another account.
`RATE_LIMIT_APP`	503	Global app limit on Meta. Temporary.	Postmatic retries accepted posts on its own; for new ones, wait a few minutes.
`SPAM_SUSPECTED`	409	Meta flagged the content as spam.	Change the caption or the images.
`MEDIA_INVALID`	400	Image or video outside the limits: `missing`, `too_many`, `too_large`, `mime`, `width`, `aspect`, `duration`, `fps`, `codec`, `audio`, `bitrate` or `moov` in `details.reason`.	See Media.
`MEDIA_FETCH_FAILED`	400	The URL answered an error or is not `https`.	Check the URL.
`MEDIA_UNREACHABLE`	400	The URL could not be reached (DNS, timeout, private address).	Make sure it is public.
`CONTAINER_EXPIRED`	409	Meta took too long to process the media.	Retries are automatic.
`CONTAINER_STUCK`	409	The container stayed `IN_PROGRESS` for over 1 hour without finishing.	Terminal — create a new post; no automatic retry.
`POST_NOT_CANCELLABLE`	409	The post already started publishing, already finished, or its time has passed.	Nothing to do; read the current state.

Infrastructure and callbacks

Code	HTTP	Cause	What to do
`PLATFORM_CREDENTIALS_MISSING`	500	Meta app configuration missing on the server.	Our fault. Contact support.
`SIGNED_REQUEST_INVALID`	400	The signature of a Meta callback does not match.	Only on the routes Meta calls.
`INTERNAL_ERROR`	500	Unexpected error.	Retry later; if it persists, contact support with the timestamp.

Per-target errors

Once accepted, a post no longer returns HTTP errors: each target in platforms[] records its outcome in errorCode and errorMessage. The codes are the same as in the tables above, plus two that only exist in that context:

`errorCode`	Meaning
`CANCELLED`	You cancelled the post before it published.
`PUBLISH_UNCONFIRMED`	Meta accepted the publish but did not confirm the result in time. The post may exist on Instagram; check before resending.

When to retry

Safe to retry: RATE_LIMIT_KEY (after the reset), RATE_LIMIT_APP, INTERNAL_ERROR. Use the same idempotencyKey so you never duplicate a post.
Do not retry without changing something: VALIDATION_ERROR, MEDIA_*, SPAM_SUSPECTED, ACCOUNT_NOT_BUSINESS.
Needs the user: TOKEN_INVALID, ACCOUNT_RESTRICTED, AUTHORIZATION_DENIED, ACCOUNT_IN_USE.