Errori

Ottieni una chiave API

Ogni errore risponde con uno stato HTTP e la stessa struttura JSON. code è il contratto che legge il tuo codice; message è scritto per una persona e può cambiare.

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 dice di più: il campo rifiutato, il motivo di una rete, la finestra di limite esaurita.
docUrl porta alla spiegazione del codice in questa pagina.
requestId identifica la richiesta: comunicalo all'assistenza.

Gli endpoint OAuth (/v1/oauth/token, /v1/oauth/authorize) rispondono nel formato RFC 6749: { "error": "invalid_grant", "error_description": "…" }.

Codici di errore

Stato	Codice	Significato
400	`invalid_request`	Il body, la query o un parametro non è valido. Un dettaglio per campo rifiutato: `field`, `code` (`required`, `is_string`, `max`…) e `message`.
400	`invalid_json`	Il body non è un JSON valido.
400	`invalid_cursor`	Il cursore non è stato restituito da Sofia API.
400	`webhook_url_invalid`	L'indirizzo del webhook non è https, o porta a un indirizzo privato.
400	`webhook_event_invalid`	Evento webhook sconosciuto.
400	`application_name_invalid`	Impostazioni › API: il nome del client manca o è troppo lungo.
400	`application_profile_invalid`	Impostazioni › API: un campo del profilo del client non è valido; il dettaglio lo indica.
400	`logo_invalid`	Impostazioni › API: il logo è rifiutato (almeno 180×180 px, PNG, JPEG o WebP, massimo 2 MB).
401	`invalid_token`	Il token manca, è sconosciuto, scaduto o revocato, oppure la persona dietro di esso ha perso i diritti che porta. Vedi l'header `WWW-Authenticate`.
401	`unauthorized`	È richiesta l'autenticazione.
402	`subscription_required`	Una scrittura reale (simulazione compresa) richiede un abbonamento attivo o una prova.
403	`insufficient_scope`	Al token manca lo scope dell'endpoint; il dettaglio lo indica.
403	`insufficient_role`	Il tuo ruolo in questo Workspace non consente questa azione.
403	`live_mode_required`	Una scrittura reale con un token di test.
403	`route_closed_to_applications`	Questo endpoint non è aperto alle applicazioni.
403	`forbidden`	L'accesso è rifiutato.
403	`session_required`	Impostazioni › API: questa azione richiede una sessione Sofia, non un token.
403	`impersonation_forbidden`	Impostazioni › API: questa azione è rifiutata in una sessione presa in prestito.
403	`workspace_owner_required`	Solo il proprietario del Workspace può farlo.
403	`workspace_member_required`	Non sei membro di questo Workspace.
404	`route_not_found`	Nessun endpoint risponde a questo metodo e a questo percorso.
404	`establishment_not_found`	Attività sconosciuta, o fuori dalla portata del token.
404	`media_not_found`	Media sconosciuto, o fuori dalla portata del token.
404	`post_not_found`	Pubblicazione sconosciuta, o fuori dalla portata del token.
404	`webhook_not_found`	Webhook sconosciuto, o di un'altra applicazione.
404	`not_found`	La risorsa non esiste.
404	`application_not_found`	Impostazioni › API: client sconosciuto.
404	`grant_not_found`	Autorizzazione sconosciuta o già revocata.
404	`personal_key_not_found`	Impostazioni › API: chiave personale sconosciuta.
404	`consent_not_found`	La richiesta di autorizzazione è scaduta o non esiste: riparti dall'endpoint di autorizzazione.
405	`method_not_allowed`	Questo metodo non è consentito su questo endpoint.
409	`post_in_flight`	Una rete sta inviando la pubblicazione: riprova l'eliminazione un momento dopo.
409	`post_not_editable`	Una rete ha già inviato la pubblicazione: non può più essere modificata.
409	`account_already_connected`	Questa rete è già collegata all'attività.
409	`webhook_limit_reached`	L'applicazione ha già 10 webhook.
409	`idempotency_in_progress`	La prima richiesta con questa `Idempotency-Key` è ancora in corso.
409	`conflict`	La richiesta è in conflitto con lo stato attuale della risorsa.
409	`scope_removal_forbidden`	Impostazioni › API: un permesso di un client può essere aggiunto ma non rimosso.
409	`public_client_has_no_secret`	Impostazioni › API: un client pubblico non ha un secret.
413	`payload_too_large`	Il file supera il limite di caricamento.
415	`unsupported_media_type`	Tipo di contenuto non supportato.
422	`post_refused`	Una rete, l'attività o il tuo piano rifiuterebbe la pubblicazione. Un dettaglio per motivo, ognuno con il suo `message`.
422	`media_import_refused`	Non è stato possibile importare il media da questo URL; il dettaglio dà il motivo.
422	`media_upload_refused`	Il file caricato non è un'immagine o un video supportato.
422	`platform_not_offered`	Questa rete non è offerta per il collegamento.
422	`idempotency_key_reused`	Questa `Idempotency-Key` è stata usata con un body diverso.
422	`unprocessable_entity`	La richiesta è comprensibile ma non può essere elaborata.
429	`rate_limit_exceeded`	Una finestra di limite è piena: attendi `Retry-After`.

Motivi di una pubblicazione rifiutata

Un post_refused elenca ogni motivo in details[].code:

Codice	Significato
`unsupported_platform`	Questa rete non è supportata.
`duplicate_platform`	La stessa rete è indicata due volte.
`unsupported_format`	Questa rete non offre questo formato.
`caption_too_long`	Il testo è troppo lungo (`max`, `actual`).
`too_many_hashtags`	Troppi hashtag (`max`, `actual`).
`too_many_mentions`	Troppe menzioni (`max`, `actual`).
`too_many_thread_posts`	Il thread è troppo lungo (`max`, `actual`).
`too_many_media`	Troppi media (`max`, `actual`).
`media_mix_refused`	Foto e video non si possono mescolare su questa rete.
`media_required`	Questa rete richiede una foto o un video.
`media_type_refused`	Questa rete non accetta questo tipo di media.
`scheduled_in_past`	`scheduledAt` è nel passato.
`scheduled_at_invalid`	Una pubblicazione programmata richiede uno `scheduledAt` futuro.
`account_not_connected`	Nessun account collegato su questa rete per questa attività.
`account_ambiguous`	Su questa rete sono collegati più account: indicane uno con `accountId`.
`media_not_found`	Il media non è nella mediateca di questa attività.
`media_url_invalid`	L'URL del media deve essere un indirizzo https pubblico.
`platform_unavailable`	Questa rete non è ancora aperta su Sofia.
`publication_quota_exceeded`	La quota di pubblicazioni del tuo piano è raggiunta.

Gestire gli errori

Ramifica su code, mai su message.
Riprova un 429 dopo Retry-After, e un 5xx con un backoff esponenziale.
Non riprovare mai un 4xx invariato: correggi prima la richiesta.
Registra requestId a ogni errore.