Codici di errore

I codici di stato HTTP di Listings API, i codici di errore SYxxxxx per Listings e Social e i tre formati delle risposte di errore restituiti dall'API v4.

Listings API usa i codici di stato HTTP convenzionali per indicare l'esito di una richiesta. I codici di errore hanno il prefisso SY e sono inclusi nella stringa di errore message, nel formato SYxxxxx: <human-readable reason>.

Codici di stato HTTP

Tre formati di risposta

La maggior parte degli errori include un array errors, al livello principale o annidato nel risultato dell'operazione, come mostrato nelle sezioni seguenti. Alcuni errori restituiscono invece un singolo oggetto error: il superamento del limite di frequenza (429) e alcuni errori a livello di richiesta (400/500 con un code come INTERNAL_SERVER_ERROR). Controlla entrambi i casi: errors è un array, error è un oggetto.

1. A livello di richiesta: errors[] al livello principale

Gli errori di autenticazione, autorizzazione e richiesta malformata interrompono l'elaborazione prima che l'operazione venga eseguita. Restituiscono il codice di stato 4xx corrispondente (vedi sopra), con l'errore al livello principale della risposta.

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Validazione delle scritture: data.<operation>.errors[] annidato

Una richiesta di creazione, aggiornamento o pubblicazione altrimenti ben formata restituisce HTTP 200. Se l'input viola una regola di business, l'errore viene segnalato in data.<operation>.errors, annidato nel payload dell'operazione stessa. In caso di successo, questo array è presente e vuoto ("errors": []).

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. A livello di gateway: un singolo oggetto error al livello principale

Il superamento del limite di frequenza e i guasti imprevisti del gateway interrompono l'elaborazione prima della traduzione e restituiscono un oggetto error con un code, un message e un correlation_id. Per il corpo della risposta 429, vedi rate_limited di seguito.

Leggi sempre data.<operation>.errors quando esegui una scrittura, anche in caso di risposta 200 con un oggetto data.<operation> popolato: una scrittura può fallire parzialmente e segnalarlo qui.

Una risposta 402 Payment Required non ha un contenitore error: code, message, doc_url e, quando c'è una fattura da pagare, pay_url si trovano al livello principale. Vedi payment_required di seguito.

Ripetere una scrittura non è a costo zero

L'API v4 non supporta Idempotency-Key: l'header viene ignorato e nessun endpoint rileva le scritture ripetute. Una chiamata di creazione, aggiornamento o pubblicazione che supera il tempo limite o restituisce un codice 5xx potrebbe comunque aver salvato le modifiche sul server, quindi ripeterla senza verifiche può produrre una sede, un post o una risposta a una recensione duplicati.

Puoi ripetere liberamente le letture con attese progressivamente più lunghe. Per una scrittura, esegui prima una lettura di verifica: cerca il record tramite una chiave che controlli (storeId, un codice del punto vendita, l'elenco delle risposte dell'interazione) e ripeti la chiamata solo se il record è effettivamente assente.

Codici comuni

I codici di validazione nell'intervallo SY10xxx corrispondono a un campo di input specifico; message indica il nome del campo o della regola per cui la validazione non è riuscita. I codici di autenticazione e autorizzazione nell'intervallo SY90xxx riguardano l'intera richiesta e vengono restituiti al livello principale con lo stato corrispondente.

Codici degli account collegati

I codici nell'intervallo SY810xx provengono dagli endpoint Connected Accounts che importano o collegano una scheda di una piattaforma di pubblicazione. Vengono restituiti annidati nel corpo della risposta con HTTP 200 (struttura della risposta 2 riportata sopra), quindi leggi data.<operation>.errors anche quando lo stato indica un esito positivo.

Codici Social

I codici nell'intervallo SY950xx provengono dagli endpoint Social: brand, connessioni e post social. Come i codici degli account collegati, sono annidati nel corpo della risposta su un HTTP 200, quindi leggi data.<operation>.error (e data.<operation>.errors sulle route per le operazioni in blocco) anche quando lo stato indica un esito positivo.

SY95042 e SY95044 sono errori relativi alle funzionalità consentite dal piano, non errori di input: riprovare senza modificare il piano produrrà lo stesso errore. SY95045, SY95046, SY95049 e SY95052 sono errori di input, correggibili nella richiesta successiva.

Codici dei diritti di utilizzo di Listings

rate_limited

429 Too Many Requests: l'account ha superato il limite di frequenza del proprio piano. Il corpo contiene la risposta di errore standard con un suggerimento retry_after_seconds, un correlation_id da citare nelle richieste di assistenza e un doc_url che rimanda a questa sezione:

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Attendi il tempo indicato da retry_after_seconds (o dall'header Retry-After, se presente), quindi riprova con backoff esponenziale. Consulta Limiti di frequenza per i limiti di ciascun piano e un'implementazione di riferimento del backoff.

payment_required

402: l'ultimo pagamento per questo account non è andato a buon fine, quindi tutti gli endpoint /api/v4 sono sospesi. Il corpo include pay_url, la pagina Stripe della fattura non pagata, quando disponibile, e l'header di risposta X-Error-Code contiene lo stesso code. Puoi comunque aprire la pagina di fatturazione nella dashboard per pagare.

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

L'accesso viene ripristinato entro un minuto dal pagamento dell'ultima fattura in sospeso. Se la fattura risulta ancora non pagata 3 giorni dopo il primo tentativo di pagamento non riuscito, l'abbonamento Listings viene annullato e le sedi dell'account vengono archiviate. Se l'account dispone anche di un abbonamento Social attivo, mantiene l'accesso a Social; altrimenti, l'account viene chiuso e le sue chiavi API smettono di funzionare.

social_payment_required

402: l'ultimo pagamento per l'abbonamento Social non è andato a buon fine, quindi gli endpoint Social (/api/v4/social/*) sono sospesi. Gli endpoint Listings continuano a funzionare. Il corpo contiene gli stessi campi di payment_required, con "code": "social_payment_required". Se la fattura risulta ancora non pagata 3 giorni dopo il primo tentativo di pagamento non riuscito, l'abbonamento Social viene annullato e i brand dell'account vengono archiviati. Un account senza abbonamento Listings viene chiuso e le sue chiavi API smettono di funzionare.

Errori del piano di controllo del portale sviluppatori

Gli endpoint per la gestione degli account e delle chiavi nel portale sviluppatori (le route API della dashboard stessa) restituiscono una risposta di errore strutturata in un unico formato, distinto dai formati REST errors[] riportati sopra. Ogni code contiene un correlation_id e un doc_url che rimanda alla sezione corrispondente di questa pagina.

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

auth_missing_key

401: non è stata fornita alcuna credenziale. Accedi di nuovo oppure invia la tua chiave come Authorization: API <your-key>.

auth_invalid_key

401: la sessione o la chiave non è valida oppure è scaduta. Autenticati di nuovo oppure genera una nuova chiave dalla dashboard.

auth_insufficient_scope

403: la credenziale è valida, ma non autorizza questa azione. Una chiave con ambito di lettura non può chiamare endpoint di scrittura; genera una chiave di scrittura se ne hai bisogno.

not_found

404: la risorsa richiesta, o una risorsa identificata tramite ID, non esiste.

conflict

409: la richiesta è in conflitto con lo stato attuale della risorsa (ad esempio, la revoca di una chiave già revocata).

validation_failed

422: il corpo della richiesta non ha superato la validazione. I campi field e details della risposta indicano l'input che ha causato l'errore.

internal_error

500: un errore imprevisto lato server. Riprova una lettura con backoff esponenziale; per una scrittura, rileggi prima il record (consulta Riprovare una scrittura ha un costo). Cita il correlation_id se contatti l'assistenza.

dependency_unavailable

503: un servizio da cui dipende l'API è temporaneamente non disponibile. Riprova con backoff.

Per 429, consulta rate_limited sopra.

Gestire gli errori nel codice

Controlla prima lo stato HTTP; poi, per le operazioni di scrittura, cerca nel corpo della risposta un array errors annidato:

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Quando usi direttamente l'API HTTP, gli stessi due controlli sono espliciti: prima il codice di stato e poi il payload della risposta:

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

L'Python SDK esegue entrambi i controlli per te: associa ogni stato HTTP a un'eccezione tipizzata e solleva un'eccezione anche per i payload di errore restituiti all'interno di un corpo 200.