Errori

Ogni errore, su qualsiasi endpoint, usa un unico formato:

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Basa la logica del tuo codice su error.code e mostra error.message alle persone. Gli errori di validazione aggiungono un array details con un messaggio per ogni campo:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Codici di errore

| Codice | HTTP | Significato | Cosa fare | |---|---|---|---| | unauthorized | 401 | Chiave mancante, sconosciuta, revocata o scaduta | Controlla l'header; genera una nuova chiave | | forbidden | 403 | Tipo di chiave errato per l'endpoint, oppure operazione non consentita | Usa una chiave di area di lavoro / partner come documentato | | insufficient_scope | 403 | Alla chiave manca un ambito necessario | Crea una chiave con l'ambito indicato nel messaggio | | plan_restricted | 403 | Il piano non comprende questa funzionalità | Passa a un piano superiore o togli la funzionalità dalla richiesta | | not_found | 404 | La risorsa non esiste — oppure appartiene a un altro tenant | Verifica l'id; le risorse altrui sono indistinguibili da quelle inesistenti | | invalid_request | 400 | JSON malformato, cursore non valido, regola di business violata | Correggi la richiesta | | validation_failed | 422 | Il corpo o la query non ha superato la validazione dello schema | Correggi i campi elencati in details | | conflict | 409 | Conflitto di stato: slug già occupato, Idempotency-Key riusata con un corpo diverso | Scegli un altro valore o una nuova chiave di idempotenza | | quota_exceeded | 422 | Una quota del piano è esaurita (link, domini, clienti) | Passa a un piano superiore o libera la quota | | rate_limited | 429 | Troppe richieste per questa chiave | Attendi i secondi indicati da Retry-After; vedi Limiti di frequenza | | not_configured | 503 | La funzionalità non è configurata in questo ambiente | Riprova più tardi o contatta l'assistenza | | internal | 500/502/504 | Errore imprevisto della piattaforma | Riprova con backoff; segnala se persiste | | invalid_click_id | 422 | Il click_id è falsificato, manomesso oppure è stato rilasciato in un'altra area di lavoro | Trasmetti il valore del parametro dell'identificatore di clic esattamente come appariva nell'URL di destinazione | | attribution_expired | 422 | Il clic è più vecchio della finestra di attribuzione dell'area di lavoro | Niente da riprovare; se serve, modifica la finestra nella dashboard |

Regole di gestione che ripagano

• Anche il 404 serve all'isolamento. Un id di un'altra area di lavoro riceve not_found, mai forbidden: l'API non rivela se un id altrui esiste.
• Riprova solo ciò che è sicuro riprovare. Ripeti internal e rate_limited con backoff. Non ripetere mai alla cieca conflict o validation_failed: è la richiesta stessa a essere sbagliata. Usa Idempotency-Key per rendere sicuri i nuovi tentativi delle operazioni di scrittura.
• GET /links non risponde mai 404. Se i filtri non trovano nulla, la risposta è un elenco vuoto; un 404 sulla collezione sarebbe ambiguo.