Erreurs Merchant API

Le risposte della Merchant API includono uno status HTTP e, in molti casi, un body JSON con campi come status e message/reason.

Status comuni

Status | Significato tipico | Cosa fare
2xx | Operazione riuscita | Procedi con il flusso
400 / 422 | Request non valida o non processabile | Controlla path, versione, campi obbligatori e encoding
401 / 403 | Autenticazione fallita o accesso negato | Verifica API Secret, instance e metodo di auth
404 | Risorsa o path non trovato | Controlla oggetto, id e versione API
405 | Method not allowed (anche segnale WAF di rate limit) | Verifica il verbo HTTP; se il volume è alto, applica backoff
403 dopo 405 | Possibile blocco rate limit WAF | Attendi e ritenta con exponential backoff

Rate limit

Soglia documentata per la piattaforma: 600 request ogni 5 minuti, enforce via AWS WAF. Dettagli: Rate limit (/docs/flowalp-pay/api/rate-limits).

405 e 403 possono avere cause diverse dal rate limit (metodo non consentito, permessi). Correlali a volume e timestamp.

Auth check fallito

Se GET /SignatureCheck/ non restituisce successo, non procedere con Gateway o transazioni finché non correggi instance e API Secret.

Esempio di risposta di successo SignatureCheck (forma tipica):

# json
{"status":"success","data":[{"id":1}]}

Best practice

• Logga status HTTP, path e correlation id lato tuo, senza API Secret.
• Distingui errori di validazione da errori di autenticazione.
• Preferisci webhook a polling aggressivo.
• In produzione usa retry solo su errori transienti (rete, 405/403 da rate limit).

Passaggi successivi

• Autenticazione (/docs/flowalp-pay/api/authentication)
• Rate limit (/docs/flowalp-pay/api/rate-limits)
• Prima richiesta API (/docs/flowalp-pay/getting-started/first-api-request)