Erreurs

Obtenir une clé API

Chaque erreur répond avec un statut HTTP et la même enveloppe JSON. code est le contrat que lit votre code ; message est écrit pour un humain et peut changer.

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 en dit plus : le champ refusé, la raison d’un réseau, la fenêtre de limite épuisée.
docUrl mène à l’explication du code sur cette page.
requestId identifie la requête : communiquez-le au support.

Les endpoints OAuth (/v1/oauth/token, /v1/oauth/authorize) répondent au format RFC 6749 : { "error": "invalid_grant", "error_description": "…" }.

Codes d’erreur

Statut	Code	Signification
400	`invalid_request`	Le corps, la requête ou un paramètre est invalide. Un détail par champ refusé : `field`, `code` (`required`, `is_string`, `max`…) et `message`.
400	`invalid_json`	Le corps n’est pas du JSON valide.
400	`invalid_cursor`	Le curseur n’a pas été renvoyé par Sofia API.
400	`webhook_url_invalid`	L’adresse du webhook n’est pas en https, ou mène à une adresse privée.
400	`webhook_event_invalid`	Événement de webhook inconnu.
400	`application_name_invalid`	Réglages › API : le nom du client est absent ou trop long.
400	`application_profile_invalid`	Réglages › API : un champ du profil du client est invalide ; le détail le nomme.
400	`logo_invalid`	Réglages › API : le logo est refusé (au moins 180×180 px, PNG, JPEG ou WebP, 2 Mo au plus).
401	`invalid_token`	Le jeton est absent, inconnu, expiré ou révoqué, ou la personne derrière a perdu les droits qu’il porte. Voir l’en-tête `WWW-Authenticate`.
401	`unauthorized`	Une authentification est requise.
402	`subscription_required`	Une écriture réelle (simulation comprise) exige un abonnement actif ou un essai.
403	`insufficient_scope`	Le jeton n’a pas le scope de l’endpoint ; le détail le nomme.
403	`insufficient_role`	Votre rôle dans ce Workspace n’autorise pas cette action.
403	`live_mode_required`	Une écriture réelle avec un jeton de test.
403	`route_closed_to_applications`	Cet endpoint n’est pas ouvert aux applications.
403	`forbidden`	L’accès est refusé.
403	`session_required`	Réglages › API : cette action demande une session Sofia, pas un jeton.
403	`impersonation_forbidden`	Réglages › API : cette action est refusée dans une session empruntée.
403	`workspace_owner_required`	Seul le propriétaire du Workspace peut faire cela.
403	`workspace_member_required`	Vous n’êtes pas membre de ce Workspace.
404	`route_not_found`	Aucun endpoint ne répond à cette méthode et ce chemin.
404	`establishment_not_found`	Établissement inconnu, ou hors de portée du jeton.
404	`media_not_found`	Média inconnu, ou hors de portée du jeton.
404	`post_not_found`	Publication inconnue, ou hors de portée du jeton.
404	`webhook_not_found`	Webhook inconnu, ou appartenant à une autre application.
404	`not_found`	La ressource n’existe pas.
404	`application_not_found`	Réglages › API : client inconnu.
404	`grant_not_found`	Autorisation inconnue, ou déjà révoquée.
404	`personal_key_not_found`	Réglages › API : clé personnelle inconnue.
404	`consent_not_found`	La demande d’autorisation a expiré ou n’existe pas : recommencez depuis l’endpoint d’autorisation.
405	`method_not_allowed`	Cette méthode n’est pas autorisée sur cet endpoint.
409	`post_in_flight`	Un réseau est en train d’envoyer la publication : réessayez la suppression un instant plus tard.
409	`post_not_editable`	Un réseau a déjà envoyé la publication : elle ne peut plus être modifiée.
409	`account_already_connected`	Ce réseau est déjà connecté à l’établissement.
409	`webhook_limit_reached`	L’application a déjà 10 webhooks.
409	`idempotency_in_progress`	La première requête avec cette `Idempotency-Key` est encore en cours.
409	`conflict`	La requête entre en conflit avec l’état actuel de la ressource.
409	`scope_removal_forbidden`	Réglages › API : une permission d’un client peut être ajoutée mais pas retirée.
409	`public_client_has_no_secret`	Réglages › API : un client public n’a pas de secret.
413	`payload_too_large`	Le fichier dépasse la limite de téléversement.
415	`unsupported_media_type`	Type de contenu non pris en charge.
422	`post_refused`	Un réseau, l’établissement ou votre forfait refuserait la publication. Un détail par raison, chacun avec son `message`.
422	`media_import_refused`	Le média n’a pas pu être importé depuis cette URL ; le détail donne la raison.
422	`media_upload_refused`	Le fichier téléversé n’est pas une image ou une vidéo prise en charge.
422	`platform_not_offered`	Ce réseau n’est pas proposé à la connexion.
422	`idempotency_key_reused`	Cette `Idempotency-Key` a servi avec un corps différent.
422	`unprocessable_entity`	La requête est comprise mais ne peut pas être traitée.
429	`rate_limit_exceeded`	Une fenêtre de limite est pleine : attendez `Retry-After`.

Raisons d’une publication refusée

Un post_refused liste chaque raison dans details[].code :

Code	Signification
`unsupported_platform`	Ce réseau n’est pas pris en charge.
`duplicate_platform`	Le même réseau est nommé deux fois.
`unsupported_format`	Ce réseau ne propose pas ce format.
`caption_too_long`	Le texte est trop long (`max`, `actual`).
`too_many_hashtags`	Trop de hashtags (`max`, `actual`).
`too_many_mentions`	Trop de mentions (`max`, `actual`).
`too_many_thread_posts`	Le fil est trop long (`max`, `actual`).
`too_many_media`	Trop de médias (`max`, `actual`).
`media_mix_refused`	Photos et vidéos ne peuvent pas être mélangées sur ce réseau.
`media_required`	Ce réseau exige une photo ou une vidéo.
`media_type_refused`	Ce réseau n’accepte pas ce type de média.
`scheduled_in_past`	`scheduledAt` est dans le passé.
`scheduled_at_invalid`	Une publication programmée exige un `scheduledAt` futur.
`account_not_connected`	Aucun compte connecté sur ce réseau pour cet établissement.
`account_ambiguous`	Plusieurs comptes sont connectés sur ce réseau : nommez-en un avec `accountId`.
`media_not_found`	Le média n’est pas dans la médiathèque de cet établissement.
`media_url_invalid`	L’URL du média doit être une adresse https publique.
`platform_unavailable`	Ce réseau n’est pas encore ouvert sur Sofia.
`publication_quota_exceeded`	Le quota de publications de votre forfait est atteint.

Gérer les erreurs

Branchez votre logique sur code, jamais sur message.
Réessayez un 429 après Retry-After, et un 5xx avec un backoff exponentiel.
Ne réessayez jamais un 4xx à l’identique : corrigez d’abord la requête.
Journalisez requestId à chaque échec.