Codici di Errore & Riferimento di Stato

Guida completa ai codici di errore di Smart Money API, codici di stato HTTP e passaggi per la risoluzione dei problemi. Comprendi le risposte di errore e risolvi rapidamente i problemi di integrazione.

Codici di Successo 2xx

Le risposte di successo indicano che la richiesta è stata elaborata correttamente.

Codice	Stato	Significato
200	OK	Richiesta riuscita. Il corpo della risposta contiene i dati richiesti.
201	Creato	La risorsa è stata creata con successo. La risposta include la nuova risorsa.
204	Nessun Contenuto	Richiesta riuscita ma non c'è contenuto da restituire (es. DELETE).

Esempio di Risposta 200

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [...],
    "pagination": {
      "page": 1,
      "limit": 50
    }
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Codici di Errore del Client 4xx

Gli errori del client indicano che la richiesta era malformata o non valida. Correggi la tua richiesta e riprova.

Codice	Stato	Causa
400	Richiesta Non Valida	Sintassi della richiesta malformata. Controlla i parametri della query, gli header e il corpo della richiesta.
401	Non Autorizzato	Credenziali di autenticazione mancanti o non valide. Controlla la tua chiave API o il token JWT.
402	Pagamento Richiesto	Il pagamento del tuo abbonamento è fallito. Aggiorna le informazioni di fatturazione nel tuo account.
403	Vietato	Autenticato ma non autorizzato per questa risorsa. Il tuo piano non include questa funzionalità.
404	Non Trovato	La risorsa non esiste. Controlla l'URL dell'endpoint e i parametri.
429	Troppe Richieste	Limite di richieste superato. Attendi prima di riprovare. Controlla l'header Retry-After.
422	Entità Non Elaborabile	Validazione fallita. I parametri della richiesta sono non validi o mancano campi obbligatori.

Esempi di Errori di Autenticazione

Chiave API Mancante (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "Credenziali di autenticazione non fornite.",
    "resolution": "Includi la tua chiave API nell'header Authorization: Authorization: Bearer sk_live_..."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Chiave API Non Valida (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "Chiave API non valida o scaduta.",
    "resolution": "Genera una nuova chiave API dalla tua console all'indirizzo https://smartmoneyapi.com/console"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Limitazione delle Richieste (429)

Quando superi la tua quota API, il server restituisce 429 Troppe Richieste. Controlla gli header della risposta per informazioni sul limite di richieste:

HTTP Headers

X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600

Errore di limite di frequenza nella risposta

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite giornaliero di richieste API (10) superato.",
    "resolution": "Passa al piano Trader ($29/mese, 400 richieste/giorno) o Pro ($79/mese, 4.000 richieste/giorno).",
    "reset_at": "2026-03-22T09:00:00Z"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Errori di validazione (422)

Gli errori di validazione si verificano quando i parametri della richiesta non sono validi o mancano campi obbligatori.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validazione della richiesta fallita.",
    "details": [
      {
        "field": "symbol",
        "error": "Coppia di trading non valida. Formato previsto: BTCUSDT"
      },
      {
        "field": "min_position_size",
        "error": "Deve essere un numero positivo"
      }
    ],
    "resolution": "Correggi gli errori di validazione e riprova."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Codici di errore del server 5xx

Gli errori del server indicano un problema dalla nostra parte. Sono temporanei e generalmente si risolvono rapidamente. Implementa una logica di riprova con backoff esponenziale.

Codice	Stato	Azione
500	Errore interno	Errore imprevisto del server. Riprova con backoff esponenziale.
502	Bad Gateway	Interruzione temporanea del servizio. Riprova dopo alcuni secondi.
503	Service Unavailable	Manutenzione o interruzione temporanea. Controlla la pagina di stato. Riprova dopo l'intervallo Retry-After.
504	Gateway Timeout	La richiesta ha impiegato troppo tempo. Il server potrebbe averla elaborata comunque. Verifica l'idempotenza.

Esempio di errore del server (503)

JSON

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Servizio temporaneamente non disponibile per manutenzione.",
    "resolution": "Riprova dopo 5 minuti. Segui lo stato su https://status.smartmoneyapi.com"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Guida alla risoluzione dei problemi

401 Unauthorized - Chiave API non valida

Problema: Ricezione di errori 401 nonostante la presenza di una chiave API.

Soluzioni:

Verifica che la chiave API sia inclusa nell'header Authorization con il prefisso "Bearer"
Controlla che la tua chiave API non sia scaduta o revocata
Assicurati di utilizzare la chiave corretta (produzione, staging o sviluppo)
Genera una nuova chiave API dalla tua console se quella attuale è persa

403 Forbidden - Funzionalità non disponibile

Problema: Ricezione di errori 403 su determinati endpoint.

Soluzioni:

Controlla il tuo livello API. Alcuni endpoint richiedono piani Trader o Pro
Aggiorna il tuo piano su /pricing.html per accedere alle funzionalità premium
Verifica che la chiave API abbia gli scope richiesti abilitati
Contatta il supporto se ritieni di dover avere accesso

429 Too Many Requests - Limite di frequenza

Problema: Ricezione di errori 429 e limitazione della frequenza.

Soluzioni:

Implementa una logica di riprova con backoff esponenziale (attendi 1s, 2s, 4s, ecc.)
Memorizza nella cache le risposte per evitare chiamate API ridondanti
Usa WebSocket per dati in tempo reale invece di interrogare endpoint REST
Aggiorna il tuo piano per ottenere quote più elevate (Trader 1,000/giorno, Pro 5.000/giorno)
Raggruppa più query in singole richieste quando possibile

400 Bad Request - Parametri non validi

Problema: Ricezione di errori 400 con richieste malformate.

Soluzioni:

Consulta la documentazione API per i parametri obbligatori e opzionali
Verifica i tipi di parametri (stringhe vs numeri, array vs oggetti)
Assicurati che il JSON sia valido e formattato correttamente
Utilizza gli URL degli endpoint corretti con i parametri di percorso appropriati
Controlla gli errori di battitura nei nomi dei parametri della query

Errori del server 5xx - Interruzioni temporanee

Problema: Ricezione di errori 500, 502, 503 o 504.

Soluzioni:

Controlla lo stato del servizio su https://status.smartmoneyapi.com
Implementa un tentativo automatico con backoff esponenziale (massimo 5-10 tentativi)
Attendi 30-60 secondi prima di riprovare gli errori 503
Utilizza l'intestazione Retry-After per determinare il momento del nuovo tentativo
Iscriviti alla pagina di stato per le notifiche sugli incidenti

Formato della risposta di errore

Tutte le risposte di errore seguono un formato coerente:

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Messaggio di errore leggibile",
    "details": {...},
    "resolution": "Passaggi per risolvere il problema"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Serve altro aiuto?

Consulta la nostra documentazione API o contatta il supporto con il tuo codice di errore e i dettagli della richiesta.

Riferimento API

Ottieni supporto

Hai domande? Consulta la nostra documentazione o contatta il supporto.

Apri console