Use error.code as your primary branching signal — it is stable across API versions. error.message is human-readable and may change.

Auth and scope errors

Code	Status	Meaning	Typical Cause	Retry
`PUBLIC_API_AUTH_REQUIRED`	`401`	Missing bearer token	`Authorization` header missing or malformed	Non-retryable until auth fixed
`PUBLIC_API_KEY_INVALID`	`401`	API key not recognized	Wrong key, revoked key, typo, wrong environment	Non-retryable until key fixed
`PUBLIC_API_KEY_EXPIRED`	`401`	API key expired	Key has `expires_at` in the past	Non-retryable until key rotated
`PUBLIC_API_SCOPE_FORBIDDEN`	`403`	Key lacks required scope(s)	Missing scopes during key creation	Non-retryable until scope/key fixed
`PUBLIC_API_WORKSPACE_FORBIDDEN`	`403`	Workspace access denied	Header scope does not match key or ownership	Non-retryable until scope/key fixed
`PUBLIC_API_BRAND_FORBIDDEN`	`403`	Brand access denied	Header scope does not match key or ownership	Non-retryable until scope/key fixed
`PUBLIC_API_CONTEXT_ERROR`	`500`	Scope resolution failed server-side	Temporary DB/service failure	Retry with backoff
`PUBLIC_API_AUTH_ERROR`	`500`	Key validation failed server-side	Temporary DB/service failure during key lookup	Retry with backoff

Request, rate limit, and idempotency errors

Code	Status	Meaning	Typical Cause	Retry
`PUBLIC_API_RATE_LIMITED`	`429`	Rate limit exceeded	Burst exceeded plan window	Retry using `Retry-After` header
`PUBLIC_API_IDEMPOTENCY_REQUIRED`	`400`	Missing `Idempotency-Key` on write	Header omitted on `POST` endpoint	Retry same payload with a key
`PUBLIC_API_IDEMPOTENCY_CONFLICT`	`409`	Reused key with different payload	Same key sent for a different logical write	Generate a new key for the new write
`PUBLIC_API_BODY_INVALID`	`400`	Invalid JSON or schema validation error	Malformed body or invalid fields	Non-retryable until payload fixed
`PUBLIC_API_QUERY_INVALID`	`400`	Invalid query parameters	Datetime format / enum / limit mismatch	Non-retryable until query fixed

Code	Status	Meaning	Retry
`PUBLIC_API_MEDIA_CREATE_FAILED`	`500`	Media record could not be created	Retry with backoff
`PUBLIC_API_UPLOAD_URL_FAILED`	`500`	Signed upload URL generation failed	Retry with backoff

Code	Status	Meaning	Retry
`PUBLIC_API_POST_LIST_FAILED`	`500`	Post listing query failed	Retry with backoff

Code	Status	Meaning	Retry
`PUBLIC_API_POST_CREATE_FAILED`	`500`	Post persistence failed	Retry with same idempotency key
`PUBLIC_API_PUBLISH_FAILED`	`422`	Provider publish failed but post state persisted	Usually non-retryable; inspect returned post and decide on new write

Code	Status	Meaning	Retry
`PUBLIC_API_POST_FETCH_FAILED`	`500`	Post fetch query failed	Retry with backoff
`PUBLIC_API_POST_NOT_FOUND`	`404`	Post does not exist or is inaccessible	Non-retryable unless ID/scope corrected

Code	Status	Meaning	Retry
`PUBLIC_API_POST_FETCH_FAILED`	`500`	Failed to load post before cancel	Retry with backoff
`PUBLIC_API_POST_NOT_FOUND`	`404`	Target post not found	Non-retryable unless ID/scope corrected
`PUBLIC_API_POST_CANCEL_INVALID_STATE`	`409`	Post is already terminal (`completed`, `failed`, `canceled`)	Non-retryable; no action needed
`PUBLIC_API_POST_CANCEL_FAILED`	`500`	Post cancel update failed	Retry with same idempotency key

Code	Status	Meaning	Retry
`PUBLIC_API_CONNECTIONS_FETCH_FAILED`	`500`	Connection listing query failed	Retry with backoff

Code	Status	Meaning	Retry
`PUBLIC_API_WEBHOOK_CREATE_FAILED`	`500`	Webhook create insert failed	Retry with same idempotency key

Code	Status	Meaning	Retry
`PUBLIC_API_USAGE_FETCH_FAILED`	`500`	Usage aggregation query failed	Retry with backoff

Retryable (with backoff):

Non-retryable (fix the request first):

Persist these fields for each API call: