Errors

Every error from the 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 (also available by sending Accept-Language: id). retryable tells you whether retrying the same request can succeed without changes.

HTTP status codes

HTTP	When
400	Malformed request
401	Invalid or missing API key
403	Missing scope, or the account 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

Platform error codes

These are the normalized codes you will see most often, translated from each platform's own error responses.

Code	Source	Message (EN)	Message (ID)	Retryable
media_too_long	TikTok duration limit	Video is longer than this account allows (over the account's max duration in seconds).	Video lebih panjang dari batas akun ini (melebihi batas durasi maksimal akun, dalam detik).	No
privacy_level_mismatch	TikTok privacy_level_option_mismatch	This privacy option is not available for this account.	Opsi privasi ini tidak tersedia untuk akun ini.	No
quota_exceeded	Instagram, Threads, TikTok	Daily posting limit reached for this account.	Batas posting harian akun ini sudah tercapai.	After the quota window resets
token_expired	Any platform	Reconnect this account to keep posting.	Hubungkan ulang akun ini agar bisa posting lagi.	No, reconnect required
permission_missing	Facebook task revoked, or scope removed	You no longer have permission to post here.	Anda tidak lagi punya izin posting di sini.	No
platform_unavailable	5xx or timeout from the platform	The platform is not responding. We will retry.	Platform sedang tidak merespons. Kami akan mencoba lagi.	Yes
too_many_pending	TikTok spam_risk_too_many_pending_share	Too many drafts are waiting in TikTok. Ask the creator to open their inbox.	Terlalu banyak draft menunggu di TikTok. Minta creator membuka inbox.	No

Generic codes

These can be returned by almost any endpoint; see each endpoint's own Errors table in the API reference for which ones actually apply to it.

Code	HTTP	When
unauthorized	401	Missing or invalid API key
insufficient_scope	403	The key does not have the scope this endpoint requires
not_found	404	Resource does not exist, or belongs to another workspace
invalid_url	400	url is not a valid public https URL
invalid_cursor	400	The cursor value is malformed or expired
invalid_range	400	A from/to date range is invalid, for example to before from or a range longer than the endpoint allows

Request-level error codes

Code	HTTP	When
consent_required	409	A TikTok target used mode: "direct" without a consent object. Use approval.mode: "link" or tiktok.mode: "inbox" instead, or supply the full consent flag; see Platform rules.
idempotency_conflict	409	The same Idempotency-Key was reused with a different request body within its 24 hour window.
idempotency_in_progress	409	The same Idempotency-Key was reused while the original request is still being processed.
payload_too_large	400	An inline base64 media upload exceeded the size limit.
unsupported_format	400	Uploaded media has a MIME type IMMA AI does not accept.
quota_exceeded_for_day	429	Used by POST /posts/batch: a specific scheduled_at day is full, without rejecting the rest of the batch.
test_key_live_account	403	An imma_test_ key was used against a live (non sandbox) account.
already_decided	409	An approval link already has a decision; only one decision per token is possible.
invalid_redirect_url	400	redirect_url is outside the workspace's allowed domains.

See Rate limits for request throttling separate from these platform quotas, and Webhooks for how post.failed events carry the same error shape.