Errori
Errori
Ogni fallimento porta un codice stabile. Ramifichi sul codice e mai sul messaggio: la formulazione può cambiare in qualsiasi momento, il codice no.
Percorsi, metodi, ambiti, nomi dei campi e codici di errore sono pubblicati in inglese, perché l'inglese è la lingua dell'interfaccia stessa: è ciò che un chiamante digita o confronta. Lo stesso vale per ogni esempio di codice, ogni payload JSON e la frase esatta che una risposta di errore porta con sé: /v1 non legge Accept-Language, e tradurre ciò che l'API invia davvero la descriverebbe in modo scorretto. Tutto ciò che viene scritto al riguardo segue la lingua di questa pagina.
L'involucro di errore
Ogni risposta fuori dalla famiglia 2xx ha la stessa forma. documentation_url punta direttamente alla voce corrispondente qui sotto, e request_id è il valore da citare in una richiesta di assistenza. details porta contesto leggibile dalle macchine: per un corpo rifiutato sono gli issues, ciascuno un JSON Pointer al campo contestato.
{
"error": {
"code": "validation_failed",
"message": "The request body failed validation.",
"documentation_url": "https://passportcraft.com/docs/api/errors#validation_failed",
"request_id": "req_9Fv2KpQ0aXbT4Lmn",
"details": {
"issues": [
{ "source": { "pointer": "/data/product_name" }, "rule": "required" }
]
}
}
}Codici
Ogni codice è collegato dalla risposta che lo porta, perciò a questa pagina si arriva quasi sempre direttamente sulla voce che serve.
invalid_key
401La chiave API fornita non è valida.
L’API restituisceThe API key provided is not valid.
Qualsiasi endpoint può restituirlo.
key_revoked
401Questa chiave API è stata revocata.
L’API restituisceThis API key has been revoked.
Qualsiasi endpoint può restituirlo.
key_expired
401Questa chiave API è scaduta.
L’API restituisceThis API key has expired.
Qualsiasi endpoint può restituirlo.
key_rotated
401Questa chiave API è stata sostituita da una rotazione e la sua finestra di sovrapposizione si è chiusa.
L’API restituisceThis API key was replaced by a rotation and its overlap window has closed.
Qualsiasi endpoint può restituirlo.
mode_mismatch
400Il prefisso della chiave non corrisponde alla credenziale. Verifichi se intendeva una chiave di prova o una di produzione.
L’API restituisceThe key prefix does not match the credential. Check whether you meant a test or a live key.
Qualsiasi endpoint può restituirlo.
insufficient_scope
403Questa credenziale non porta l'ambito richiesto da questa operazione.
L’API restituisceThis credential does not carry the scope required for this operation.
Quali endpoint lo restituiscono
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
organization_not_found_or_not_granted
404Organizzazione inesistente.
L’API restituisceNo such organization.
Quali endpoint lo restituiscono
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
resource_not_found
404Risorsa inesistente.
L’API restituisceNo such resource.
Quali endpoint lo restituiscono
- get
/categories/{category}/schema - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - get
/organizations/{organization}/imports/{id}
wildcard_not_supported
400Il carattere jolly «-» per l'organizzazione è riservato e non è ancora supportato.
L’API restituisceThe "-" organization wildcard is reserved and not yet supported.
Quali endpoint lo restituiscono
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
validation_failed
422Il corpo della richiesta non ha superato la validazione.
L’API restituisceThe request body failed validation.
Quali endpoint lo restituiscono
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
invalid_request
400La richiesta non è comprensibile.
L’API restituisceThe request could not be understood.
Qualsiasi endpoint può restituirlo.
method_not_allowed
405L'endpoint esiste ma non risponde a questo metodo HTTP. L'intestazione Allow del rifiuto elenca quelli a cui risponde.
L’API restituisceThis endpoint does not support that HTTP method. The Allow header lists the ones it does.
payload_too_large
413Il corpo della richiesta supera quanto questo endpoint accetta. details.limit_bytes riporta il tetto applicato.
L’API restituisceThe request body is larger than this endpoint accepts.
Qualsiasi endpoint può restituirlo.
unsupported_media_type
415Il corpo della richiesta non è arrivato come application/json.
L’API restituisceThe request body must be sent as application/json.
Quali endpoint lo restituiscono
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
idempotency_conflict
409Questa Idempotency-Key è già stata usata con un corpo di richiesta diverso.
L’API restituisceThis Idempotency-Key was already used with a different request body.
Quali endpoint lo restituiscono
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
precondition_failed
412La risorsa è cambiata rispetto alla versione fornita.
L’API restituisceThe resource changed since the version you supplied.
resource_busy
409Un’altra richiesta sta modificando questa risorsa. Attenda il tempo indicato dall’intestazione Retry-After, poi riprovi.
L’API restituisceAnother request is modifying this resource. Wait for the Retry-After header, then retry.
Quali endpoint lo restituiscono
cursor_invalid
400Il cursore di impaginazione non è valido, è scaduto oppure è stato inviato con filtri diversi.
L’API restituisceThe pagination cursor is invalid, expired, or was sent with different filters.
no_subscription
402Questa organizzazione non ha un abbonamento attivo.
L’API restituisceThis organization has no active subscription.
Quali endpoint lo restituiscono
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
payment_overdue
402La pubblicazione è disattivata finché il pagamento resta in arretrato.
L’API restituiscePublishing is disabled while payment is overdue.
Quali endpoint lo restituiscono
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
gtin_required
422Serve un GTIN prima che questo passaporto possa essere pubblicato.
L’API restituisceA GTIN is required before this passport can be published.
Quali endpoint lo restituiscono
wrong_status
409Il passaporto non si trova in uno stato che consenta questa operazione.
L’API restituisceThe passport is not in a status that allows this operation.
Quali endpoint lo restituiscono
not_trashed
409Si può ripristinare solo un passaporto che si trova nel cestino.
L’API restituisceOnly a trashed passport can be restored.
Quali endpoint lo restituiscono
publish_limit_reached
402Questa organizzazione ha esaurito tutte le pubblicazioni consentite dal suo piano.
L’API restituisceThis organization has used every publish slot its plan allows.
Quali endpoint lo restituiscono
unit_limit_reached
402Questo passaporto porta più unità di quante ne consenta il piano.
L’API restituisceThis passport carries more units than the plan allows.
Quali endpoint lo restituiscono
document_missing
422Un campo obbligatorio è soddisfatto solo da un documento che non è più allegato.
L’API restituisceA required field is satisfied only by a document that is no longer attached.
Quali endpoint lo restituiscono
delegation_required
403Il deposito richiede una delega attiva, verificata sul portale al momento della chiamata.
L’API restituisceFiling requires an active delegation, verified against the portal at call time.
Quali endpoint lo restituiscono
attestation_required
403Questa operazione richiede un'attestazione accettata da una persona individuata per nome presso il marchio.
L’API restituisceThis operation requires an attestation accepted by a named person at the brand.
Quali endpoint lo restituiscono
test_mode_refused
403Le credenziali di prova non possono eseguire questa operazione.
L’API restituisceTest-mode credentials cannot perform this operation.
Quali endpoint lo restituiscono
rate_limited
429Troppe richieste.
L’API restituisceToo many requests.
Qualsiasi endpoint può restituirlo.
internal_error
500Qualcosa è andato storto dalla nostra parte.
L’API restituisceSomething went wrong on our side.
Qualsiasi endpoint può restituirlo.
configuration_error
500Il servizio è configurato male. Non è un problema della Sua richiesta.
L’API restituisceThe service is misconfigured. This is not a problem with your request.
Qualsiasi endpoint può restituirlo.
Avvisi
Un avviso non è un rifiuto. Arriva insieme a un 200, su una chiamata riuscita, e segnala qualcosa su cui vale la pena intervenire.
environmental_claim_detected
200Il passaporto contiene formulazioni di carattere ambientale. La pubblicazione è riuscita e il passaporto è online. Dal 27 settembre 2026 la direttiva (UE) 2024/825 impone al professionista che immette il prodotto sul mercato di disporre di elementi a sostegno di tali asserzioni.