Convenzioni comuni delle risposte

Le API seguono una struttura di risposta uniforme. Conoscere questa convenzione ti aiuta a leggere più velocemente la documentazione tecnica e a scrivere integrazioni più semplici da mantenere.

La regola generale è questa: gli endpoint applicativi restituiscono una risposta JSON con quattro campi, sempre presenti:

{
  "error": 0,
  "message": null,
  "data": {},
  "meta": null
}

Questa struttura è molto utile perché rende prevedibile il modo in cui leggere il risultato di una chiamata, anche quando cambia il contenuto effettivo di data.

SDK ufficiali

Gli SDK ufficiali per PHP e Python leggono già questa struttura: restituiscono data e meta come oggetti tipizzati e trasformano le risposte di errore in eccezioni.

La struttura standard

`error`

Il campo error indica se la chiamata è andata a buon fine.

0 significa che la richiesta è stata gestita correttamente;
un valore maggiore di 0 è il codice dell'errore (vedi Codici di errore).

In caso di errore, il codice HTTP della risposta resta comunque il primo riferimento da controllare, ma il campo error ti permette di distinguere i casi con lo stesso codice HTTP: per esempio, un 403 per scope mancante da un 403 per funzione non disponibile.

`message`

Il campo message contiene un messaggio testuale associato alla risposta.

Nei casi di successo è normalmente null, mentre nei casi di errore contiene una descrizione del problema, pensata per chi sviluppa l'integrazione.

`data`

Il campo data contiene il risultato vero e proprio della chiamata.

A seconda dell'endpoint, può essere:

un oggetto singolo;
un array di elementi, negli endpoint di elenco;
null, nelle risposte di errore e in alcune operazioni che non hanno nulla da restituire.

`meta`

Il campo meta contiene informazioni aggiuntive sulla risposta:

negli endpoint di elenco paginati contiene i dati di paginazione;
nelle risposte di errore di validazione contiene il dettaglio degli errori per campo;
in tutti gli altri casi è null.

Esempio di risposta di successo

Una tipica risposta di successo per un endpoint che restituisce un singolo oggetto ha questa forma:

{
  "error": 0,
  "message": null,
  "data": {
    "purchase_id": 123,
    "suspended": false
  },
  "meta": null
}

In questo caso:

error vale 0, quindi la chiamata è andata a buon fine;
message non contiene informazioni particolari;
data contiene il risultato richiesto;
meta è null, perché non è un elenco paginato.

Quando `data` è un array

Gli endpoint di elenco restituiscono un array dentro data e i dati di paginazione in meta.

Per esempio:

{
  "error": 0,
  "message": null,
  "data": [
    {
      "id": 101,
      "name": "Elemento A"
    },
    {
      "id": 102,
      "name": "Elemento B"
    }
  ],
  "meta": {
    "total": 45,
    "count": 2,
    "pages": 23,
    "page": 1,
    "per_page": 2
  }
}

Qui il contenuto principale è l'array data, mentre meta descrive la paginazione. I dettagli sono nella guida Gestione della paginazione.

Codici HTTP di successo

Il codice HTTP di una risposta positiva dice che tipo di risultato aspettarti:

Codice	Quando	Corpo
`200 OK`	Lettura o modifica completata	La struttura standard, con il risultato in `data`
`201 Created`	Creazione di una risorsa, ad esempio un record DNS o un upload	La struttura standard, con la risorsa creata in `data`; l'header `Location` indica l'URL della nuova risorsa, quando è consultabile con una `GET`
`202 Accepted`	Operazione avviata in background	La struttura standard, con un oggetto `Task` in `data`
`204 No Content`	Eliminazione completata	Nessun corpo

Le risposte 204 non hanno corpo: il tuo client non deve tentare di decodificarle come JSON.

Quando `data` contiene un task

Le operazioni che richiedono tempo, come il riavvio di un server, il ripristino di un backup o l'emissione di un certificato, vengono gestite in modo asincrono. In questi casi la risposta è 202 Accepted e data non contiene la risorsa finale ma un oggetto Task:

{
  "error": 0,
  "message": null,
  "data": {
    "task_id": 98765,
    "purchase_id": 123,
    "task_status": {
      "status_code": "TO_EXECUTE",
      "status_name": "Da eseguire"
    },
    "executed_instructions": 0,
    "total_instructions": 4,
    "is_started": false,
    "ask_user_error": null,
    "date_started": "2026-10-19T09:30:00Z"
  },
  "meta": null
}

In questi casi la risposta va interpretata così:

la richiesta è stata accettata;
l'elaborazione è stata avviata;
il risultato finale non è ancora disponibile.

Per seguire l'avanzamento, interroga periodicamente GET /api/v3/tasks/{task_id}, il cui URL trovi anche nell'header Location della risposta. La lettura dei task richiede lo scope purchases:read. Il campo task_status.status_code può valere:

TO_EXECUTE: in coda;
MACHINE: in esecuzione;
WAIT: in pausa;
HUMAN_INTERVENTION: in verifica da parte di un operatore;
ASK_USER: in attesa di dati da parte tua, da inviare con POST /api/v3/tasks/{task_id}/data;
DONE: completato;
FAIL: non riuscito.

Se non c'è nulla da avviare, ad esempio perché la configurazione richiesta è già attiva, alcuni di questi endpoint rispondono 200 OK con data uguale a null.

Per chi integra le API, è importante non dare per scontato che una risposta positiva significhi "operazione già completata": un 202 significa "operazione presa in carico correttamente".

Formato dei dati

Alcune convenzioni valgono per tutti gli endpoint:

le date e ore sono in formato ISO 8601 in UTC, ad esempio 2026-10-19T09:30:00Z; le date senza ora sono nel formato 2026-10-19;
tutti i campi previsti dallo schema sono sempre presenti nella risposta: un valore assente è null, non un campo mancante;
nelle richieste con corpo JSON, i campi non previsti dallo schema dell'endpoint vengono rifiutati con un errore di validazione, così un errore di battitura in un nome di campo non passa inosservato;
nelle date e ore inviate nel corpo delle richieste è richiesto lo stesso formato UTC con la Z finale.

Risposte di errore applicative

Quando una richiesta fallisce, la risposta segue questa struttura:

{
  "error": 1200,
  "message": "Domain not found",
  "data": null,
  "meta": null
}

In questo caso:

error è il codice dell'errore, maggiore di zero;
message spiega il problema in forma testuale;
data è null;
meta è null, tranne negli errori di validazione.

Errori di validazione

Quando i dati inviati non sono validi, la risposta è 400 Bad Request con errore 1000, e meta.errors contiene il dettaglio per ciascun campo. La chiave è il percorso del campo, il valore l'elenco dei messaggi:

{
  "error": 1000,
  "message": "Invalid request data: domain_prefix: is required; configuration.ram: must be <= 64",
  "data": null,
  "meta": {
    "errors": {
      "domain_prefix": ["is required"],
      "configuration.ram": ["must be <= 64"]
    }
  }
}

I campi annidati sono indicati con il punto (configuration.ram), gli elementi di una lista con l'indice (ids[3]).

Codici di errore

Codice	Stato HTTP	Significato
`1000`	400	Dati non validi: dettaglio per campo in `meta.errors`
`1001`	400	Richiesta non valida, senza dettaglio per campo
`1100`	401	Token mancante, non valido, scaduto o revocato: richiedi un nuovo token e ripeti la chiamata una sola volta
`1101`	403	Il token non ha gli scope richiesti dall'endpoint
`1102`	403	Il token non è valido per questa API (audience diversa)
`1200`	404	Risorsa inesistente o non appartenente al tuo account, oppure endpoint inesistente
`1202`	405	Metodo HTTP non previsto per questo path: l'header `Allow` indica quelli ammessi
`1300`	429	Troppe richieste: attendi i secondi indicati dall'header `Retry-After`
`1400`	409	Conflitto con una regola o con lo stato attuale della risorsa, ad esempio un servizio sospeso o un'operazione già in corso
`1500`	500	Errore interno
`1601`	403	Operazione non consentita: funzione non inclusa nel servizio, non disponibile per i sub-account o richiesta da un IP non autorizzato
`1700`	402	Pagamento rifiutato dal fornitore: gli ordini restano da pagare

L'elenco completo, con i casi che producono ciascun codice, come gestirli e gli errori dell'endpoint del token, è in Codici di errore.

Dal punto di vista dell'integrazione, è utile mostrare o registrare il contenuto di message, ma conviene anche tenere traccia del codice HTTP, del codice error e dell'header X-Request-Id, che identifica la richiesta e va indicato all'assistenza in caso di problemi.

Le eccezioni più importanti

La struttura standard con error, message, data e meta vale per tutte le risposte JSON delle API, con alcune eccezioni importanti da conoscere.

Token OAuth2

L'endpoint /oauth/token non restituisce il wrapper standard applicativo.

La risposta contiene direttamente i campi:

token_type;
expires_in;
access_token;
scope;
audience.

Questo comportamento è normale: segue il formato tipico delle risposte OAuth2.

Errori OAuth2

Anche gli errori dell'endpoint token seguono una struttura diversa, con campi come:

error, ad esempio invalid_client, invalid_scope o rate_limited;
error_description;
error_uri.

In questo caso il campo error è normalmente una stringa, non un codice numerico come nelle risposte applicative standard.

Download di file

Gli endpoint che restituiscono file da scaricare non rispondono con il wrapper JSON standard in caso di successo.

Quando il download va a buon fine, la risposta contiene direttamente il file binario, ad esempio un PDF o un XML, insieme agli header HTTP del download.

Solo in caso di errore questi endpoint restituiscono una risposta JSON di errore standard. Vedi Download di file.

Eliminazioni

Le risposte 204 No Content non hanno corpo, quindi nemmeno il wrapper standard.

Buone pratiche

non assumere che data abbia sempre la stessa forma;
leggi meta negli endpoint di elenco e negli errori di validazione;
non leggere solo il codice HTTP ignorando il contenuto JSON;
gestisci i 202 Accepted seguendo il task fino al suo completamento;
gestisci separatamente le eccezioni, come OAuth2, download file e risposte 204;
usa la documentazione tecnica del singolo endpoint per sapere cosa aspettarti in data.

In sintesi

Le API applicative restituiscono risposte JSON con una convenzione semplice e uniforme:

error indica l'esito;
message fornisce un messaggio leggibile in caso di errore;
data contiene il risultato;
meta contiene la paginazione o il dettaglio degli errori di validazione.

Una volta compresa questa struttura, leggere le pagine tecniche e sviluppare un'integrazione diventa molto più immediato.

La struttura standard​

error​

message​

data​

meta​

Esempio di risposta di successo​

Quando data è un array​

Codici HTTP di successo​

Quando data contiene un task​

Formato dei dati​

Risposte di errore applicative​

Errori di validazione​

Codici di errore​

Le eccezioni più importanti​

Token OAuth2​

Errori OAuth2​

Download di file​

Eliminazioni​

Buone pratiche​

In sintesi​