Errors

The API uses standard HTTP status codes. Error bodies are JSON in one of three shapes.

Error shapes

Generic error — status and a message:

{
  "statusCode": 404,
  "message": "…",
  "error": "Not Found"
}

Business error with a code — branch on code, not on the message:

{ "code": "connection_missing", "platform": "instagram" }

Validation error — what is wrong with the request body:

{
  "formErrors": [],
  "fieldErrors": { "mediaId": ["media_required"] }
}

Messages are human-readable, may be localized and may change. Branch on the status and code — they are stable.

Status codes

Status	When
200, 201	Success.
202	Accepted for asynchronous processing (publications).
204	Success without a body (deletions).
400	Invalid parameters or body.
401	Missing or invalid token.
403	Not allowed for this token.
404	Not found. A resource that belongs to someone else also returns 404.
409	Conflict with the current state: plan limit reached, network not connected.
429	Publishing rate limit exceeded — retry after a pause.
503	A dependency (for example Meta) is temporarily unavailable.

Common codes

Code	Status	Meaning
project_limit_reached	409	The plan’s project limit is reached.
connection_missing	409	The network isn’t connected to the project.
connection_not_ready	409	The connection needs re-authorization.
media_not_found	400	The image for mediaId was not found.
media_aspect_ratio	400	The image doesn’t fit the Instagram feed (4:5 to 1.91:1).
text_required, media_required, media_not_allowed	400	The publication body doesn’t match its kind.
<platform>_<kind>_unsupported	400	The network doesn’t support this kind, e.g. instagram_text_unsupported.
<platform>_text_too_long	400	The text is over the network’s limit.
scheduled_at_past	400	scheduledAt is in the past.
invalid_timezone	400	timezone is not a known IANA zone.
publication_dispatched	409	The publication was already sent and can’t be edited.
meta_unavailable	503	Meta is temporarily unavailable.

Each endpoint lists its errors in the API reference.