Errors

Get an API key

Every error answers with an HTTP status and the same JSON envelope. code is the contract your code reads; message is written for a human and may change.

json

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

details says more: the refused field, the reason of a network, the exhausted rate window.
docUrl leads to the explanation of the code on this page.
requestId identifies the request: give it to support.

The OAuth endpoints (/v1/oauth/token, /v1/oauth/authorize) answer in the RFC 6749 format: { "error": "invalid_grant", "error_description": "…" }.

Error codes

Status	Code	Meaning
400	`invalid_request`	The body, the query or a parameter is invalid. One detail per refused field: `field`, `code` (`required`, `is_string`, `max`…) and `message`.
400	`invalid_json`	The body is not valid JSON.
400	`invalid_cursor`	The cursor was not returned by Sofia API.
400	`webhook_url_invalid`	The webhook address is not https, or leads to a private address.
400	`webhook_event_invalid`	Unknown webhook event.
400	`application_name_invalid`	Settings › API: the name of the client is missing or too long.
400	`application_profile_invalid`	Settings › API: a field of the client profile is invalid; the detail names it.
400	`logo_invalid`	Settings › API: the logo is refused (at least 180×180 px, PNG, JPEG or WebP, 2 MB at most).
401	`invalid_token`	The token is missing, unknown, expired or revoked, or the person behind it lost the rights it carries. See the `WWW-Authenticate` header.
401	`unauthorized`	Authentication is required.
402	`subscription_required`	A live write (dry run included) needs an active subscription or trial.
403	`insufficient_scope`	The token lacks the scope of the endpoint; the detail names it.
403	`insufficient_role`	Your role in this Workspace does not allow this action.
403	`live_mode_required`	A real write with a test token.
403	`route_closed_to_applications`	This endpoint is not open to applications.
403	`forbidden`	Access is refused.
403	`session_required`	Settings › API: this action needs a Sofia session, not a token.
403	`impersonation_forbidden`	Settings › API: this action is refused in a borrowed session.
403	`workspace_owner_required`	Only the owner of the Workspace can do this.
403	`workspace_member_required`	You are not a member of this Workspace.
404	`route_not_found`	No endpoint answers this method and path.
404	`establishment_not_found`	Unknown establishment, or out of reach of the token.
404	`media_not_found`	Unknown media, or out of reach of the token.
404	`post_not_found`	Unknown post, or out of reach of the token.
404	`webhook_not_found`	Unknown webhook, or one of another application.
404	`not_found`	The resource does not exist.
404	`application_not_found`	Settings › API: unknown client.
404	`grant_not_found`	Unknown authorization, or already revoked.
404	`personal_key_not_found`	Settings › API: unknown personal key.
404	`consent_not_found`	The authorization request expired or does not exist: start again from the authorization endpoint.
405	`method_not_allowed`	This method is not allowed on this endpoint.
409	`post_in_flight`	A network is sending the post: retry the deletion a moment later.
409	`post_not_editable`	A network already sent the post: it can no longer be edited.
409	`account_already_connected`	This network is already connected to the establishment.
409	`webhook_limit_reached`	The application already has 10 webhooks.
409	`idempotency_in_progress`	The first request with this `Idempotency-Key` is still running.
409	`conflict`	The request conflicts with the current state of the resource.
409	`scope_removal_forbidden`	Settings › API: a permission of a client can be added but not removed.
409	`public_client_has_no_secret`	Settings › API: a public client has no secret.
413	`payload_too_large`	The file is above the upload limit.
415	`unsupported_media_type`	Unsupported content type.
422	`post_refused`	A network, the establishment or your plan would refuse the post. One detail per reason, each with its `message`.
422	`media_import_refused`	The media could not be imported from this URL; the detail gives the reason.
422	`media_upload_refused`	The uploaded file is not a supported image or video.
422	`platform_not_offered`	This network is not offered for connection.
422	`idempotency_key_reused`	This `Idempotency-Key` was used with a different body.
422	`unprocessable_entity`	The request is understood but cannot be processed.
429	`rate_limit_exceeded`	A rate limit window is full: wait for `Retry-After`.

Reasons of a refused post

A post_refused lists each reason in details[].code:

Code	Meaning
`unsupported_platform`	This network is not supported.
`duplicate_platform`	The same network is named twice.
`unsupported_format`	This network does not offer this format.
`caption_too_long`	The text is too long (`max`, `actual`).
`too_many_hashtags`	Too many hashtags (`max`, `actual`).
`too_many_mentions`	Too many mentions (`max`, `actual`).
`too_many_thread_posts`	The thread is too long (`max`, `actual`).
`too_many_media`	Too many media (`max`, `actual`).
`media_mix_refused`	Photos and videos cannot be mixed on this network.
`media_required`	This network needs a photo or a video.
`media_type_refused`	This network does not accept this type of media.
`scheduled_in_past`	`scheduledAt` is in the past.
`scheduled_at_invalid`	A scheduled post needs a future `scheduledAt`.
`account_not_connected`	No account connected on this network for this establishment.
`account_ambiguous`	Several accounts are connected on this network: name one with `accountId`.
`media_not_found`	The media is not in the library of this establishment.
`media_url_invalid`	The media URL must be a public https address.
`platform_unavailable`	This network is not open on Sofia yet.
`publication_quota_exceeded`	The publication quota of your plan is reached.

Handling errors

Branch on code, never on message.
Retry 429 after Retry-After, and 5xx with an exponential backoff.
Never retry a 4xx unchanged: fix the request first.
Log requestId with every failure.