Errors (API)

This is the API reference summary of error handling. For the full list of normalized error codes, sources and retry guidance, see Errors, which this page links to rather than repeats.

Shape

Every error from the REST API and MCP server comes back in one shape, regardless of which platform caused it:

{
  "error": {
    "code": "media_too_long",
    "message": "Video is longer than this account allows (180s).",
    "message_id": "Video lebih panjang dari batas akun ini (180 detik).",
    "target_id": "tgt_2",
    "field": "media[0]",
    "retryable": false,
    "docs": "https://getimma.com/docs/errors#media_too_long"
  }
}

• message is English, message_id is Bahasa Indonesia; you can also request the Indonesian message directly with Accept-Language: id.
• retryable tells you whether retrying the same request, unchanged, could succeed.
• target_id and field are present when the error is scoped to one target or one field, and omitted otherwise.

HTTP status codes

HTTP	When
400	Malformed request
401	Invalid or missing API key
403	Missing scope, or the resource does not belong to this workspace
404	Resource not found
409	Idempotency conflict, or the resource is not in a valid state for this action
422	Platform validation failed (see issues[] in the response)
429	Rate limited; see the Retry-After header
5xx	Server error

Where to look next

• Errors: the full table of platform error codes (media_too_long, privacy_level_mismatch, quota_exceeded, token_expired, permission_missing, platform_unavailable, too_many_pending) and request-level codes (consent_required, idempotency_conflict, payload_too_large, unsupported_format, quota_exceeded_for_day).
• Idempotency: idempotency_conflict and idempotency_in_progress in detail.
• Rate limits: 429 responses and the Retry-After header.
• Webhooks: how a post.failed event carries this same error shape in its payload.