WWaSparks Social Developers

Reference

Error codes

Every error code the API returns, with its status and what to do about it.

All errors use the body described in Errors, limits and idempotency: error.code, message, request_id and details. Branch on the code. The API reference lists the codes each operation can return.

400 Bad request

Code Meaning What to do
validation_failed A field is missing or invalid. details.fields lists every field at fault, with the account_id where it applies to one account. Fix the listed fields.
unsupported_for_platform The account's platform, or its capabilities, do not allow this. No call was made to the platform. Check capabilities first. See Platform notes.
media_not_ready A media item in the request is not READY. details.media_id names it. Finish the upload with POST /v1/media/{mediaId}/complete.
tenant_required A partner key on the Content API without X-Tenant-Id. Send the org's external_ref. See Operator mode.

401 Unauthorized

Code Meaning What to do
invalid_api_key The key is missing, malformed or unknown. Check the Authorization: Bearer header.
key_revoked The key was revoked. Use another key.
key_expired The key's expires_at has passed. Mint a new key.

402 Payment required

Code Meaning What to do
quota_exceeded A plan limit is reached. details has limit, used and max. Free up the resource or move the org to a plan with a higher limit. See Billing and usage.

403 Forbidden

Code Meaning What to do
insufficient_permission The key lacks the permission the operation needs. Use a key that has it. See Authentication.
partner_key_not_allowed A partner key on the Content API, and the partner is not in operator mode. Use an org key, or ask us to enable operator mode.
org_key_not_allowed An org key on the Partner API. Use a partner key.
org_suspended The org is suspended. Resume it with POST /v1/partner/orgs/{orgId}/resume.
org_closed The org is closed for good. Nothing: closing is permanent.

404 Not found

Code Meaning What to do
not_found The resource does not exist, or is not yours. The two look the same on purpose. With X-Tenant-Id, also an unknown org ref. Check the id, the key and the tenant.

409 Conflict

Code Meaning What to do
idempotency_conflict You reused an Idempotency-Key with a different request. Use a new key for a new request.
invalid_state The resource is not in a state that allows this: editing a published post, acting on a deleted comment, a duplicate code or external_ref, a sync already running. Read the resource and decide.
publish_outcome_unknown A target was set aside after a failure while publishing, and may or may not be live. Check the platform, then retry the target only if it is not there.

422 Unprocessable

Code Meaning What to do
account_needs_reauth The account's credential is no longer accepted. Reconnect the account.
reply_window_closed The 24-hour messaging window is closed. Check reply_window first. See Comments and inbox.
platform_rejected The platform refused the request. details has platform, platform_code, platform_subcode and platform_message; all four are present, and null when unknown. Show the reason to your user or fix the content.

429 Too many requests

Code Meaning What to do
rate_limited You are over a rate limit. The Retry-After header says how long to wait. Wait, then retry.
platform_rate_limited The social platform is limiting this account. Back off for that account.

5xx Server errors

Code Meaning What to do
internal_error (500) Something went wrong on our side. Retry with backoff. If it persists, send us the request_id.
platform_unavailable (503) The social platform is not answering. Retry with backoff.

Codes on resources

Two codes also appear inside a resource, not only as an HTTP error:

A failed post target or message carries an error with a code and a message.

Next: API reference