Codici di risposta ed errori

L’X API fornisce i seguenti codici di risposta ed errore per aiutare a comprendere e risolvere i problemi nell’immediato. Usa la guida al debug e l’indice degli errori qui sotto per ulteriori informazioni.

Le risposte con esito positivo sono indicate da un codice HTTP della serie 200 e da un payload in formato JSON contenente gli oggetti richiesti, creati, modificati o eliminati, insieme alla descrizione dell’interpretazione della tua richiesta da parte del server.

Le risposte di errore sono restituite con un codice HTTP non appartenente alla serie 200. Codici di errore diversi indicano motivazioni diverse per un errore. L’X API tenta di restituire codici di stato HTTP appropriati per ogni richiesta.

​

Codici di stato HTTP di X API v2

Codice	Testo	Descrizione	Suggerimenti per la risoluzione dei problemi
200	OK	La richiesta è stata eseguita correttamente.
400	Bad Request	La richiesta non è valida o non può essere servita. Un messaggio di errore di accompagnamento fornirà ulteriori dettagli. Le richieste senza autenticazione o con parametri di query non validi sono considerate non valide e produrranno questa risposta.	Ricontrolla il formato della tua query JSON. Ad esempio, se la tua regola contiene virgolette doppie associate a un operatore di corrispondenza esatta o ad altri operatori, potresti doverle eseguire l’escape usando una barra rovesciata per distinguerle dalla struttura del formato JSON.
401	Unauthorized	Si è verificato un problema nell’autenticazione della tua richiesta. Potrebbe dipendere da credenziali di autenticazione mancanti o errate. Questo codice può essere restituito anche in altre circostanze non definite.	Verifica di utilizzare il metodo di autenticazione corretto e che le tue credenziali siano corrette.
403	Forbidden	La richiesta è stata compresa, ma è stata rifiutata oppure l’accesso non è consentito. Un messaggio di errore di accompagnamento spiegherà il motivo.	Verifica che il tuo account sviluppatore includa l’accesso all’endpoint che stai tentando di utilizzare. Potresti anche dover inserire la tua App in allowlist (ad es. Engagement API o Ads API) o richiedere l’accesso.
404	Not Found	L’URI richiesto non è valido oppure la risorsa richiesta, ad esempio un utente, non esiste.	Verifica di utilizzare parametri validi e l’URI corretto per l’endpoint che stai utilizzando.
409	Connection Exception	Restituito quando si tenta di connettersi a un filtered stream che non ha regole.	Verifica di aver creato almeno una regola per lo stream a cui ti stai connettendo. Il filtered stream restituirà solo Post che corrispondono a una regola attiva. Se non ci sono regole, lo stream non restituirà alcun Post.
429	Too Many Requests	Restituito quando una richiesta non può essere servita perché il limite di velocità dell’App o il Post cap sono stati esauriti. Vedi Rate Limiting.	Controlla il numero di richieste per intervallo di tempo consentite con l’endpoint che stai utilizzando. Attendi il reset dell’intervallo. Distribuisci le richieste nel tempo per evitare di raggiungere i limiti di velocità oppure esegui l’upgrade al piano dati successivo disponibile.
500	Internal Server Error	Qualcosa non funziona. Di solito si tratta di un errore temporaneo, ad esempio in caso di carico elevato o se un endpoint ha temporaneamente problemi.	Controlla la pagina di stato di X API o il forum della community degli sviluppatori per verificare se altri stanno riscontrando problemi simili, oppure attendi e riprova più tardi.
501	Unimplemented	X API non supporta questo endpoint e non può soddisfare la richiesta.
503	Service Unavailable	I server di X sono attivi, ma sovraccarichi di richieste. Riprova più tardi.	Controlla la pagina di stato di X API o il forum della community degli sviluppatori per verificare se altri stanno riscontrando problemi simili, oppure attendi e riprova più tardi.

Quando si verifica un errore durante una richiesta, nel corpo della risposta vengono restituite informazioni dettagliate sull’errore per aiutare a diagnosticare il problema. Un campo type, che è un URI, indica la natura del problema, mentre campi aggiuntivi forniscono ulteriori dettagli. I campi type, title e detail vengono sempre restituiti in questi body (vedi tabella sotto). Eventuali campi aggiuntivi, come nell’esempio seguente, varieranno a seconda del tipo di errore.

{
  "client_id": "101010101",
  "required_enrollment": "Standard Basic",
  "registration_url": "https://developer.twitter.com/en/account",
  "title": "Client Non Autorizzato",
  "detail": "Questa richiesta deve essere effettuata utilizzando un account sviluppatore approvato che abbia accesso all'endpoint richiesto. Per maggiori informazioni, consulta la nostra documentazione.",
  "reason": "client-not-enrolled",
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​

Errori parziali

In alcuni casi potresti vedere gli errori descritti sopra in una risposta con codice di stato 200. In tali casi, l’endpoint è progettato per restituire i dati disponibili, fornendo al contempo errori dettagliati su ciò che non è stato possibile restituire.

Ad esempio, l’endpoint di lookup dei Posts consente a una App sviluppatore di X di richiedere più di un id. Se alcuni di quei Post sono disponibili ma uno di essi è stato eliminato, i Post disponibili verranno restituiti nel campo data della risposta. Nel payload verrà incluso anche un campo errors, che indica quali Post richiesti non è stato possibile restituire. Viene utilizzato lo stesso formato dei errori di richiesta completi per facilitare la diagnosi dei problemi.

​

Informazioni sugli errori

Ogni tipo di problema indica la natura dell’errore riscontrato. Un elenco completo dei problemi che potresti incontrare è disponibile anche nella nostra specifica API.

La X API tenta di restituire codici di stato HTTP appropriati per ogni richiesta.

Titolo	Tipo	Descrizione
Problema generico	about:blank	Problema generico senza ulteriori informazioni oltre a quelle fornite dal codice di stato HTTP.
Problema di richiesta non valida	https://api.X.com/2/problems/invalid-request	Problema che indica che questa richiesta non è valida. Se la richiesta include un corpo POST, assicurati che il contenuto sia JSON valido e che sia conforme alla specifica OpenAPI.
Problema risorsa non trovata	https://api.X.com/2/problems/resource-not-found	Problema che indica che un determinato Post, Utente, ecc. non esiste.
Problema risorsa non autorizzata	https://api.X.com/2/problems/not-authorized-for-resource	Problema che indica che non sei autorizzato a visualizzare un determinato Post, Utente, ecc.
Problema client non autorizzato	https://api.X.com/2/problems/client-forbidden	Problema che indica che al tuo client non è consentito effettuare questa richiesta.
Problema risorsa non consentita	https://api.X.com/2/problems/disallowed-resource	Problema che indica che la risorsa richiesta viola i criteri di questa API.
Problema autenticazione non supportata	https://api.X.com/2/problems/unsupported-authentication	Problema che indica che l’autenticazione utilizzata non è supportata.
Problema limite di utilizzo superato	https://api.X.com/2/problems/usage-capped	Problema che indica che è stato superato un limite di utilizzo.
Problema di connessione	https://api.X.com/2/problems/streaming-connection	Problema che indica un’anomalia nella connessione.
Problema client disconnesso	https://api.X.com/2/problems/client-disconnected	Il tuo client si è disconnesso.
Problema disconnessione operativa	https://api.X.com/2/problems/operational-disconnect	Sei stato disconnesso per motivi operativi.
Problema limite regole	https://api.X.com/2/problems/rule-cap	Hai superato il numero massimo di regole.
Problema lunghezza regole	https://api.X.com/2/problems/rule-length	Hai superato il numero massimo di caratteri consentiti nella tua query o regola in base al tuo livello di accesso. Vedi livelli di accesso.
Problema regole non valide	https://api.X.com/2/problems/invalid-rules	La regola che hai inviato non è valida.
Problema regole duplicate	https://api.X.com/2/problems/duplicate-rules	La regola che hai inviato è un duplicato.

​

Suggerimenti per la risoluzione dei problemi

Debug del codice

Quando si sviluppa un’applicazione, è normale imbattersi talvolta in errori o problemi imprevisti. Di seguito trovi alcuni suggerimenti su come effettuare il debug del tuo codice:

Inizia scomponendo il problema in parti più piccole per individuare dove si trova l’errore. Ad esempio, se stai integrando un endpoint REST o di streaming, il problema potrebbe dipendere da uno dei seguenti elementi:

• L’endpoint richiede una autenticazione corretta.
• L’endpoint richiede parametri e intestazioni validi. Eventuali regole di filtraggio devono essere costruite utilizzando gli operatori corretti e la sintassi appropriata.
• L’URI dell’endpoint deve essere corretto e, nel caso degli endpoint REST, deve essere utilizzato il metodo HTTP corretto.
• I dati o la risorsa a cui stai tentando di accedere potrebbero non essere accessibili (ad esempio, i dati privati sono disponibili solo agli utenti autenticati).
• Il tuo attuale pacchetto dati ti dà accesso solo a determinati endpoint e a specifici limiti di velocità. Consulta il developer portal per maggiori dettagli.
• Il tuo codice utilizza una libreria di terze parti per integrare l’endpoint nel tuo progetto.
• Il tuo codice deve analizzare correttamente la risposta dell’endpoint.

Leggi il messaggio di errore associato. Questo dovrebbe darti una buona indicazione del problema. Usa le tabelle nella sezione dei codici di errore e di risposta per suggerimenti di risoluzione specifici per ciascun codice di errore.

Per gli endpoint REST, puoi utilizzare un client REST come Postman o Insomnia per convalidare i passaggi da (1) a (5) sopra (consulta la nostra guida “Guida introduttiva a Postman”). Se la richiesta con il client REST restituisce un codice di stato 200 (successo), puoi presumere che il problema risieda nel tuo codice o nella libreria che stai utilizzando, e non nella richiesta all’endpoint in sé.

Per gli endpoint di streaming, puoi utilizzare cURL (uno strumento da riga di comando per inviare o ricevere richieste utilizzando la sintassi degli URL) per verificare se il problema riguarda la richiesta all’endpoint (passaggi da (1) a (5) sopra) o il tuo codice (passaggi da (6) a (7) sopra).

Problemi di autenticazione

• Verifica di utilizzare il metodo di autenticazione corretto richiesto dall’endpoint. Questo può essere identificato tramite la pagina di riferimento dell’API dell’endpoint.
• Verifica che le tue credenziali di autenticazione siano corrette. Puoi controllare o rigenerare le chiavi e i token della tua App nella sezione Apps della dashboard per sviluppatori (in “Details”).
• Verifica di aver correttamente autorizzato la tua richiesta OAuth 1.0a con oauth_nonce, oauth_signature e oauth_timestamp.
• Se il problema persiste, considera l’uso di una libreria OAuth, di un client REST come Postman o Insomnia, o di xurl.

Consulta la nostra guida sull’autenticazione per ulteriori informazioni su tutti i punti sopra.

Problemi di limitazione e Post cap

Un errore 429 può verificarsi se raggiungi un limite di velocità per un determinato endpoint o se raggiungi un Post cap.

Se viene restituito lo specifico errore “Too many requests”, hai raggiunto il limite di velocità dell’endpoint. In altre parole, hai superato il numero massimo di richieste consentite per un endpoint in un determinato periodo di tempo.

Nota che i limiti di velocità sono impostati a livello di App e a livello utente.

• Livello X App indica il numero di richieste consentite quando si utilizza OAuth 2.0 App-Only, in cui i limiti di velocità sono determinati globalmente per l’intera App. Ad esempio, se un metodo consente 15 richieste per finestra di limite di velocità, ti consente di effettuare 15 richieste per finestra per conto della tua X App. Questo limite è considerato completamente separato dal limite a livello utente. Per saperne di più, consulta la nostra guida su OAuth 2.0 App-Only.
• Livello contesto utente indica il numero di richieste che possono essere effettuate per Access Token utente quando si utilizza Contesto utente OAuth 1.0a o OAuth 2.0 Authorization Code con PKCE. Ad esempio, se un metodo consente 15 richieste per finestra di limite di velocità, consente 15 richieste per finestra e per Access Token utente. Per saperne di più, consulta la nostra guida su come ottenere gli Access Tokens di un utente con OAuth 1.0a e OAuth 2.0.

Inizia verificando i limiti di velocità per l’endpoint che stai utilizzando. Puoi trovare queste informazioni nella pagina di riferimento dell’API dell’endpoint e nel nuovo dashboard del developer portal.

Consulta la nostra documentazione per ulteriori informazioni sui limiti di velocità, inclusi come utilizzare le intestazioni HTTP per monitorare la situazione della tua App rispetto a un determinato limite di velocità, come riprendersi da un codice di errore 429 per limite di velocità e suggerimenti per evitare di incorrere in limitazioni:

• Limiti di velocità per gli endpoint v2

Se hai ricevuto lo specifico errore “Usage cap exceeded: Monthly product cap”, significa che hai raggiunto il Post cap per il tuo livello di accesso. Trovi molti dettagli su questi Post cap nella nostra pagina di documentazione.

Problemi di Post mancanti

Segui i passaggi seguenti se ti aspettavi che venisse restituito un Post, ma non è stato recapitato dall’endpoint.

• Controlla la tua regola per assicurarti di utilizzare gli operatori e la sintassi corretti. Suddividi la regola in clausole più piccole per verificare di utilizzare la sintassi corretta.
• Se l’account da cui è stato inviato il Post era protetto al momento della creazione del Post, il Post non verrà restituito, anche se l’account è pubblico al momento della richiesta all’endpoint. In genere puoi verificarlo utilizzando la Ricerca avanzata di X: se un Post non viene visualizzato tramite la funzionalità Ricerca avanzata di X, dovresti presumere che non verrà restituito dall’endpoint.

I passaggi seguenti si applicano solo agli endpoint di streaming:

• Eri connesso allo stream quando è stato inviato il Post? Ricorda che il timestamp fornito nell’Oggetto Post indica l’ora in UTC. Se hai riscontrato una disconnessione quando è stato inviato il Post, rivedi le funzionalità di ripristino e ridondanza disponibili per recuperare eventuali dati mancati.
• La tua regola era in vigore quando è stato inviato il Post? Ricorda che il timestamp fornito nell’Oggetto Post indica l’ora in UTC.

Problemi di disconnessione per buffer pieno

Potresti ricevere uno dei seguenti errori quando il tuo stream non riesce a tenere il passo con la velocità con cui stiamo distribuendo i dati e la tua App non consuma i dati dallo stream abbastanza rapidamente:

This stream has been disconnected because your client was unable to keep up with us.

This stream has been disconnected for operational reasons.

Consentiamo per un certo periodo che la consegna vada in ritardo e disponiamo di un buffer di staging temporaneo per ogni stream lato nostro; ma se non recuperi, avviamo una disconnessione per consentirti di riconnetterti al punto corrente. Tieni presente che questo può comportare una perdita di dati (per i dati presenti nel buffer al momento della disconnessione per buffer pieno).

Questi problemi possono verificarsi in caso di forti picchi di dati. In generale, consigliamo di utilizzare un processo di buffering separato dal processo di elaborazione per consumare rapidamente i dati.

Se sei un cliente Enterprise che utilizza endpoint v1.1, puoi trovare maggiori informazioni su come ottimizzare la tua App per prevenire disconnessioni di questo tipo nei nostri articoli sulla connessione e sul consumo di dati in streaming qui e qui.

È disponibile una serie di strumenti per recuperare Post persi a causa di una disconnessione, inclusi quelli elencati di seguito. Nota che i seguenti strumenti sono disponibili solo con endpoint v1.1 al livello di accesso Enterprise.

• Redundant Connections - Con più connessioni, consuma lo stream da più server per evitare perdite di dati quando una viene disconnessa.
• Replay - Recupera i dati degli ultimi 5 giorni utilizzando uno stream separato.
• Backfill - Riconnettiti entro 5 minuti e riparti da dove ti eri fermato.
• Historical PowerTrack - Recupera i dati dall’intero archivio di X.

​

Richiedi assistenza

Il forum della community di X è a tua disposizione per porre domande tecniche sulla piattaforma per sviluppatori di X. È un forum di discussione in cui troverai quesiti di altri sviluppatori e informazioni tecniche su vari argomenti relativi all’uso della X API.

Ti invitiamo a partecipare rispondendo alle domande e intervenendo nelle discussioni sul nostro forum. Anche i dipendenti di X sono presenti per fornire supporto.

Forum della community di X

​

Prima di pubblicare una domanda

• Cerca nella documentazione per sviluppatori di X informazioni relative al tuo problema
• Cerca nel forum della community eventuali domande simili di altri sviluppatori
• Consulta le linee guida del forum della community

​

Quando pubblichi una domanda, assicurati di includere le seguenti informazioni

• Una descrizione del problema
• La chiamata all’API effettuata (includendo le intestazioni, se possibile)
• La risposta di X ricevuta (includendo eventuali messaggi di errore)
• Cosa ti aspettavi di ricevere
• Elenco dei passaggi eseguiti per la risoluzione del problema
• Elenco dei passaggi necessari per riprodurre il problema
• Se pertinente, l’intervallo temporale in cui si è verificato il problema
• Se pertinente, l’App ID, l’ID del Post, ecc.
• Eventuali frammenti di codice o screenshot pertinenti

Includi un solo argomento/domanda per post.

Se hai richieste di funzionalità o feedback, inviali tramite il Modulo di feedback della X Developer Platform.

Per problemi relativi alle Policy, come la sospensione dell’App, contatta il supporto Policy.

Per problemi relativi a X, come assistenza per l’accesso o per l’account, utilizza l’Help Desk di X.