Errori

L’API REST utilizza codici di stato HTTP standard e restituisce un corpo di errore JSON:

json

{ "error": "unauthorized", "message": "Missing or invalid API key" }

# Codici di stato

Stato	`error`	Quando
`400`	`invalid-argument`	Corpo malformato o campo obbligatorio mancante.
`401`	`unauthorized`	Chiave API mancante, non valida o revocata.
`403`	`permission-denied`	Al di là dell’autorizzazione del tuo piano (una funzione non inclusa nel tuo piano).
`404`	`not-found`	Nessun link/campagna/job con quell’id, oppure non di proprietà del tuo account.
`405`	`method_not_allowed`	Quel metodo HTTP non è supportato nel percorso.
`409`	`failed-precondition`	La risorsa non è in uno stato che consente l’operazione — ad es. modifica di un link bloccato, o emissione di codici serializzati oltre la tua quota Enterprise (il limite è nel messaggio).
`429`	`rate_limited` / `resource-exhausted`	Limite di velocità per chiave superato (`rate_limited` — include un timestamp `retry_at` e intestazioni di risposta `X-RateLimit-*`) oppure quota del piano esaurita (`resource-exhausted`). Aspetta e riprova.
`5xx`	`internal`	Qualcosa è andato storto da parte nostra; sicuro ritentare letture idempotenti.

Gli errori a livello di trasporto (autenticazione, routing, rate-limiting) utilizzano codici in snake_case; gli errori a livello di risorsa utilizzano kebab-case (la convenzione Firebase callable). Branchia sempre in base allo stato HTTP, non alla stringa error.

# Proprietà

Ogni lettura e scrittura è limitata all’account a cui la chiave API si risolve. La richiesta del link o della campagna di un altro account restituisce 404 (non 403) — non riveliamo che esiste.

# Job asincroni

I job Batch e serialized mint accettano la richiesta (200, queued), quindi mostrano gli errori nello stato del job (status: "failed" con un motivo), non nella risposta HTTP originale. Esegui sempre il polling del job.

# Verifica

Gli endpoint pubblici di verifica non restituiscono mai errori su un numero seriale sconosciuto — restituiscono status: "unknown" (un codice falso/non emesso è una risposta significativa, non un 404).

# Successivo

Autenticazione · il riferimento API completo.