In short
Social Relay errors use { error: { code, message, details, requestId } }. Insufficient tokens return insufficient_tokens. Partial posts mean some network legs succeeded—retry only failed legs with Idempotency-Key discipline on create.
Error envelope
Include requestId when opening an in-app Support ticket so operators can correlate logs. Never log full API keys or OAuth tokens.
Common codes
- unauthorized (401) — fix or rotate key
- insufficient_tokens (402) — top up Funding or Support ticket for early access
- validation_failed / 422 — fix payload from details
- profile_not_found (404) — wrong or cross-tenant id
- rate_limited (429) — backoff
- upstream_error — network adapter or Meta/LinkedIn failure
Partial success
Do not treat partial as total failure. Show per-network status in your UI. Retry only failed legs so successful Facebook posts are not duplicated.