Errors

Every error has a stable code and a message you can show to a person.

Errors use standard HTTP status codes and always have this shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Instagram requires an image or video. Attach media or remove that channel.",
    "details": {}
  }
}

Branch on code; it never changes. message is written for people and may be reworded. details adds context where it helps.

Status	Code	Meaning
401	unauthorized	Missing, invalid, expired or revoked API key.
403	forbidden_scope	The key doesn’t have the permission this needs. details.required names it.
403	plan_required	The organization’s plan doesn’t include API access.
404	not_found	It doesn’t exist, or this key can’t see it.
409	conflict	The request clashes with the current state, for example editing a post that is already publishing.
409	duplicate_post	The same post was created in the last 5 minutes. details.postId is the existing post.
409	limit_reached	A plan limit: monthly posts, active keys or storage.
422	validation_failed	The request is invalid or a platform rule isn’t met. For malformed input, details.issues lists each problem.
429	rate_limited	Too many requests this minute. details.resetsAt says when to retry.
429	quota_exceeded	Monthly request quota used up. details.resetsAt is the start of next month.
500	internal_error	Something went wrong on our side. Retry with backoff.

Retrying

• Retry 429 after details.resetsAt, and 500 with exponential backoff.
• Don’t retry 4xx errors other than 429 unchanged: fix the request first.
• Retrying a post creation is safe: an identical post within 5 minutes returns duplicate_post instead of posting twice.