Errori — API di PassportCraft

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, codici di errore e nomi delle regole di convalida 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.

Risposta

{
  "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

401

La chiave API fornita non è valida.

L’API restituisceThe API key provided is not valid.

Qualsiasi endpoint può restituirlo.

key_revoked

401

Questa chiave API è stata revocata.

L’API restituisceThis API key has been revoked.

Qualsiasi endpoint può restituirlo.

key_expired

401

Questa chiave API è scaduta.

L’API restituisceThis API key has expired.

Qualsiasi endpoint può restituirlo.

key_rotated

401

Questa 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

400

Il 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

403

Questa 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

organization_not_found_or_not_granted

404

Organizzazione inesistente, oppure questa chiave non ha alcuna concessione su di essa. Una concessione termina quando qualcuno la revoca o quando termina la collaborazione dell'organizzazione con il suo partner; a quel punto l'organizzazione non compare più in GET /organizations.

L’API restituisceNo such organization.

Quali endpoint lo restituiscono

resource_not_found

404

Risorsa inesistente.

L’API restituisceNo such resource.

Quali endpoint lo restituiscono

wildcard_not_supported

400

Il 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

validation_failed

422

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

invalid_request

400

La richiesta non è comprensibile.

L’API restituisceThe request could not be understood.

Qualsiasi endpoint può restituirlo.

method_not_allowed

405

L'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

413

Il 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

415

Il corpo della richiesta non è arrivato come application/json.

L’API restituisceThe request body must be sent as application/json.

Quali endpoint lo restituiscono

idempotency_conflict

409

Questa 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

already_exists

409

Esiste già una risorsa con questo identificativo.

L’API restituisceA resource with this identifier already exists.

Quali endpoint lo restituiscono

gtin_in_use

409

Questo GTIN appartiene a un altro passaporto. details indica passport, product_name e role (lead o variant). Usi quel passaporto o un altro GTIN.

L’API restituisceThis GTIN belongs to another passport. Use that passport or choose a different GTIN.

Quali endpoint lo restituiscono

variant_limit_reached

422

Questo passaporto ha raggiunto il limite di varianti. details contiene limit, current e requested. Crei un secondo passaporto per aggiungerne altre. Il limite non dipende dal piano.

L’API restituisceThis passport has reached its variant limit. Create a second passport to add more.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/variants

variant_review_required

409

Questo passaporto contiene taglie e colori inseriti da un assistente. Una persona li verifica prima: legga GET …/variants/review, poi pubblichi con la sua impronta. details contiene agent_written_count e l’URL della verifica.

L’API restituisceThis passport carries sizes and colours an assistant wrote. A person reviews them first: read the review, then publish with its fingerprint.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/publish

variant_review_changed

409

Taglie e colori sono cambiati dopo la verifica indicata da questa impronta. Rilegga la verifica e pubblichi con l’impronta attuale. details contiene agent_written_count.

L’API restituisceThe sizes and colours changed after the review this fingerprint names. Read the review again and publish with its current fingerprint.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/publish

precondition_failed

412

La risorsa è cambiata: dalla versione fornita, oppure mentre la sua richiesta era in corso. Il current_version che indichiamo è la versione che abbiamo letto, non necessariamente quella ora memorizzata: rilegga il passaporto invece di calcolare a partire da essa.

L’API restituisceThe resource changed since the version you supplied.

Quali endpoint lo restituiscono

resource_busy

409

Un’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

delete/organizations/{organization}/passports/{id}/documents/{documentId}

cursor_invalid

400

Il 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.

Quali endpoint lo restituiscono

no_subscription

402

Questa organizzazione non ha un abbonamento attivo.

L’API restituisceThis organization has no active subscription.

Quali endpoint lo restituiscono

plan_required

402

Il piano di questa organizzazione non include questa operazione.

L’API restituisceThis organization’s plan does not include this operation.

Quali endpoint lo restituiscono

payment_overdue

402

La pubblicazione è disattivata finché il pagamento resta in arretrato.

L’API restituiscePublishing is disabled while payment is overdue.

Quali endpoint lo restituiscono

gtin_required

422

Serve 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

409

Il 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

409

Si può ripristinare solo un passaporto che si trova nel cestino.

L’API restituisceOnly a trashed passport can be restored.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/restore

publish_limit_reached

402

Questa 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

post/organizations/{organization}/passports/{id}/publish

unit_limit_reached

402

Questo 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

422

Un 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

post/organizations/{organization}/passports/{id}/publish

document_feeds_extraction

409

Questo documento è la traccia della provenienza dei valori di un passaporto, quindi resta finché quel passaporto esiste. Non è stato scollegato nulla.

L’API restituisceThis document is the record of where a passport’s values came from, so it stays while that passport exists. Nothing was detached.

Quali endpoint lo restituiscono

delete/organizations/{organization}/passports/{id}/documents/{documentId}

document_feeds_reading

409

Questo documento supporta valori della batteria registrati e non può essere eliminato finché quei record esistono. Apra il modello di batteria per esaminarli.

L’API restituisceThis document supports recorded battery values and cannot be deleted while those battery records exist. Open the battery model to review those records.

invalid_input

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_observed_on

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_source

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_field

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

invalid_note

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_value

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_document_id

400

Il corpo della richiesta non ha superato la validazione.

L’API restituisceThe request body failed validation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_required

400

Questa batteria ha già uno stato. Scelga uno stato invece di cancellarlo.

L’API restituisceThis battery already has a status. Choose a status instead of clearing it.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_transition_forbidden

409

Una batteria non può tornare a Originale dopo un altro stato né cambiare stato dopo Rifiuto.

L’API restituisceThis battery’s status cannot return to Original or change after Waste.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_history_conflict

409

Questo stato sarebbe in conflitto con la cronologia registrata della batteria. Verifichi la data e lo stato.

L’API restituisceThis status would conflict with the battery’s recorded history. Check the date and status.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_reading_document_unavailable

400

Risorsa inesistente.

L’API restituisceNo such resource.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

delegation_required

403

Il 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

post/organizations/{organization}/passports/{id}/affichage

attestation_required

403

Questa 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

post/organizations/{organization}/passports/{id}/affichage

test_mode_refused

403

Le credenziali di prova non possono eseguire questa operazione.

L’API restituisceTest-mode credentials cannot perform this operation.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/affichage

human_approval_required

202

Il connettore ha richiesto una pubblicazione. Una persona dell'organizzazione deve approvarla e non è stato pubblicato nulla.

L’API restituisceA person at your organization must approve this publish. The request was recorded and is waiting for them — give them the link in `details.review_url`. Nothing has been published.

connector_writes_drafts_only

409

Il connettore agente può modificare solo una bozza. Un passaporto che il pubblico vede già richiede una persona.

L’API restituisceThis product is already visible to the public, so an assistant cannot change it. A person has to make the change — give them the editor link in `details.review_url`.

Quali endpoint lo restituiscono

unit_status_not_allowed

422

Scelga uno dei cinque stati della batteria ammessi indicati nei dettagli.

L’API restituisceChoose one of the five permitted battery statuses in `details.allowed`, or leave the status empty.

portal_unavailable

502

Il portale francese non ha risposto in tempo. La sua dichiarazione può essere stata registrata oppure no. Invii di nuovo la richiesta con una nuova Idempotency-Key: nulla viene dichiarato due volte. Riutilizzare la stessa chiave restituisce soltanto questo stesso errore.

L’API restituisceThe French affichage portal did not answer. If the declaration had already been sent, it may still have been recorded — check the passport before filing it again.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/affichage

storage_unavailable

503

Non siamo riusciti a confermare se i file caricati siano presenti nell’archivio, quindi non è stato pubblicato nulla. La sua richiesta non ha nulla di errato: riprovi dopo il tempo indicato dall’intestazione Retry-After.

L’API restituisceWe could not confirm whether the uploaded files are in storage, so nothing was published. Nothing is wrong with your request — retry after the delay in the Retry-After header.

Quali endpoint lo restituiscono

entitlement_unavailable

503

Non siamo riusciti a confermare i diritti di questa organizzazione, quindi non è stato depositato nulla. Non è un giudizio sull’abbonamento: riprovi dopo il tempo indicato dall’intestazione Retry-After.

L’API restituisceWe could not confirm this organization’s entitlement, so nothing was filed. This is not a statement about the plan — retry after the delay in the Retry-After header.

Quali endpoint lo restituiscono

post/organizations/{organization}/passports/{id}/affichage

scope_exceeds_key

422

La concessione chiede un ambito di cui la chiave non dispone nella propria organizzazione. Ciò che viene concesso per un cliente non supera mai ciò che la chiave stessa possiede.

L’API restituisceA grant cannot carry a scope the key does not hold on its own organization

Quali endpoint lo restituiscono

post/organizations/{organization}/grants

france_mandate_required

403

Non è ancora possibile concedere filings:write per questo cliente. Una persona della Sua organizzazione deve prima confermare, nello spazio di lavoro del cliente, di disporre dell'autorizzazione scritta del cliente a depositare in Francia.

L’API restituiscefilings:write needs the client's written authorisation, affirmed in its workspace, before it can be granted

Quali endpoint lo restituiscono

post/organizations/{organization}/grants

grantor_not_seated

403

La persona che ha creato la chiave usata per questa chiamata non occupa più un posto nello spazio di lavoro di questo cliente, quindi nessuno può risultare come autore della concessione. Crei una nuova chiave nelle impostazioni.

L’API restituisceThe person who created this key no longer holds a seat in this organization

Quali endpoint lo restituiscono

post/organizations/{organization}/grants

key_not_grantable

409

La chiave indicata in key_id è revocata, scaduta, in corso di sostituzione oppure è la connessione di un assistente. In nessuno di questi casi può ricevere una concessione.

L’API restituisceThis key cannot be granted: it is revoked, expired, being replaced, or an assistant connection

Quali endpoint lo restituiscono

post/organizations/{organization}/grants

grant_conflict

409

La chiave ha già qui una concessione con ambiti diversi. Revochi quella concessione, poi ne conceda una nuova con gli ambiti che desidera.

L’API restituisceThis key already holds a grant here with different scopes; revoke it, then grant again

Quali endpoint lo restituiscono

post/organizations/{organization}/grants

rate_limited

429

Troppe richieste.

L’API restituisceToo many requests in a short time. Wait a moment, then try again.

Qualsiasi endpoint può restituirlo.

internal_error

500

Qualcosa è andato storto dalla nostra parte.

L’API restituisceSomething went wrong on our side.

Qualsiasi endpoint può restituirlo.

configuration_error

500

Il 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.

Rifiuti dell’app PassportCraft

L’app in cui ha effettuato l’accesso richiama le proprie route, e queste route rifiutano con i codici seguenti. Non fanno parte del contratto /v1 e possono cambiare in qualsiasi momento. Sono elencati qui perché un messaggio visto nell’app, o un articolo di supporto, abbia dove rimandare.

billing_managed_by_partner

Il partner dell’area di lavoro gestisce la sua fatturazione. Il pagamento, il portale di fatturazione e i cambi di piano vengono tutti rifiutati con questo codice.

L’API restituisceBilling for this workspace is managed by the partner that pays for it

partner_role_fixed

Questa persona lavora per il partner dell’area di lavoro. Il suo ruolo qui segue quello che ha presso il partner e non può essere modificato; un proprietario o un amministratore può rimuoverla.

L’API restituisceA partner member's role follows their role at the partner

home_members_only

Solo il proprietario o gli amministratori dell’area di lavoro stessa possono farlo, ad esempio accettare, rifiutare o interrompere un partner. Il personale di un partner non può, qualunque sia il suo ruolo. Può ruotare una chiave solo se è stata creata dal personale del suo partner in quest’area di lavoro e agisce soltanto su quest’area di lavoro.

L’API restituisceOnly the workspace's own owner or administrator can do this

client_already_linked

Quest’area di lavoro ha già un partner, o una richiesta di un partner a cui non ha ancora risposto.

L’API restituisceThis workspace already has a partner, or a request it has not answered

partner_chain_not_allowed

Lo spazio di lavoro gestisce già dei clienti oppure è già gestito da un partner. Un’organizzazione può essere un partner oppure il cliente di un partner, mai entrambi, quindi questa collaborazione non può iniziare.

L’API restituisceAn organization can manage clients or be managed by a partner, not both

not_a_partner

L’organizzazione indicata in X-Organization non gestisce alcun cliente.

L’API restituisceThis organization does not manage clients

partner_staff_only

Solo il personale del partner che gestisce può farlo, ad esempio confermare l’autorizzazione scritta di un cliente per le dichiarazioni francesi di coût environnemental.

L’API restituisceOnly the partner's staff can do this

link_not_found

Con questo id non esiste alcun rapporto di partnership per quest’area di lavoro.

L’API restituisceLink not found

link_not_pending

Quella richiesta ha già ricevuto una risposta.

L’API restituisceThis request has already been answered

link_not_accepted

Il rapporto di partnership non è attivo: è ancora in attesa di una risposta, oppure è terminato.

L’API restituisceThis link is not active

same_organization

Un’organizzazione non può gestire se stessa.

L’API restituisceAn organization cannot manage itself

organization_not_found

Nessun’area di lavoro corrisponde all’indirizzo o all’email indicati.

L’API restituisceOrganization not found

organization_header_required

La richiesta non ha indicato un’area di lavoro. Invii lo slug dell’area di lavoro nell’header X-Organization.

L’API restituisceThe X-Organization header is required

organization_not_a_member

La persona che ha eseguito l’accesso non è membro dell’area di lavoro indicata in X-Organization.

L’API restituisceNot a member of this organization

continuity_pending

Il piano pagato dal partner è ancora in corso. La fatturazione di quest’area di lavoro cambia alla data fino a cui è stato pagato.

L’API restituisceThe current plan runs to the date it was paid to; billing for this workspace changes after that

partner_terms_missing

Per questo partner non sono ancora registrate condizioni di fatturazione, quindi sul suo account non può essere aperto alcun piano.

L’API restituisceThis partner has no billing terms recorded

partner_customer_missing

Il partner non ha ancora un account di pagamento.

L’API restituisceThis partner has no payment account yet

partner_card_missing

Il partner non ha alcun metodo di pagamento registrato. Ne aggiunge uno nella propria pagina Fatturazione.

L’API restituisceThis partner organization has no payment method on file

client_already_subscribed

Quest’area di lavoro paga già un proprio abbonamento.

L’API restituisceThis workspace already has its own subscription

plan_below_current

Il piano scelto è inferiore a quello su cui si trova attualmente quest’area di lavoro.

L’API restituisceThat plan is smaller than the one this workspace is on

continuity_not_available

Non c’è alcun periodo pagato da un partner precedente da proseguire per quest’area di lavoro.

L’API restituisceThere is nothing to continue on this workspace

yearly_not_accepted

Un piano annuale sull’account di un partner richiede prima l’accettazione scritta del partner per l’impegno annuale.

L’API restituisceThis partner has not accepted the annual term in writing; record it before opening a yearly plan

stripe_refused

Il fornitore di pagamento ha rifiutato la richiesta.

L’API restituisceStripe refused the request

payment_pending

L’esito del pagamento non è ancora noto. Verifichi lo stato della richiesta esistente; non crei un altro cliente e non invii un altro pagamento.

L’API restituisceThe payment result is not yet known. Check its status before starting another payment.

price_changed

Il prezzo confermato è diverso dall’ultima anteprima. Verifichi il prezzo aggiornato prima di inviare di nuovo la richiesta. Non è stato creato alcun cliente.

L’API restituisceThe price changed. Review the current amount before creating the client.

price_unavailable

L’anteprima del prezzo non è disponibile. La ricarichi prima di creare il cliente. Non è stato creato alcun cliente.

L’API restituisceThe price is unavailable. No client was created. Try the review again later.

price_changed_after_create

Il cliente è stato creato sul piano gratuito. Il prezzo è cambiato e il tentativo di pagamento non saldato è stato chiuso in sicurezza. Contatti l’assistenza per attivare il piano; non crei di nuovo il cliente.

L’API restituisceThe client was added on Free. The reviewed payment did not proceed. Contact support to activate the plan.

creation_token_invalid

Questa verifica non corrisponde all’utente, all’area di lavoro o ai dati del cliente. Verifichi nuovamente i dati corretti. Se ha già inviato una richiesta di creazione e l’esito è sconosciuto, contatti l’assistenza invece di ricominciare.

L’API restituisceThis creation review is invalid. If creation has already started, check its status or contact support.

creation_token_expired

L’autorizzazione alla creazione è scaduta. Verifichi prima eventuali richieste di creazione esistenti; se non ne ha inviate, verifichi nuovamente il pagamento.

L’API restituisceThis creation review expired. Check any existing operation before reviewing a new creation.

creation_operation_expired

Lo stato conservato di questa richiesta di creazione non è più disponibile. Contatti l’assistenza prima di procedere; non crei di nuovo il cliente.

L’API restituisceThis operation status is no longer available. Contact support before creating another client.

creation_conflict

Questa richiesta di creazione è già associata a dati diversi. Verifichi la richiesta originale o contatti l’assistenza; non avvii un’altra creazione.

L’API restituisceThis operation belongs to different creation details. Check the original operation or contact support.

creation_unavailable

La verifica prima della creazione non è disponibile. Riprovi più tardi. Se l’esito di una richiesta di creazione è sconosciuto, ne verifichi lo stato anziché inviarla nuovamente.

L’API restituisceCreation review is unavailable. Try again later; check the status of any creation already started.

client_not_managed

L’organizzazione indicata non è un cliente gestito dalla Sua organizzazione.

L’API restituisceThat organization is not a client your organization manages

keys_admin_partner_only

keys:admin può essere assegnato solo a una chiave che appartiene a un’organizzazione che gestisce clienti.

L’API restituiscekeys:admin can only be granted on the own keys of an organization that manages clients

grant_not_found

Nessuna chiave di un’altra organizzazione ha accesso a quest’area di lavoro con questo id.

L’API restituisceNo key from another organization holds a grant here under that id

Regole di convalida

Queste sono le regole che il contenuto stesso del passaporto può violare, in qualsiasi categoria. Un nome di regola le arriva in tre punti: dentro error.details.issues in un 422, dentro issues nel 200 dell’endpoint di convalida e dentro error.detail.issues su una riga di importazione massiva. Creazione, modifica e importazione rifiutano un valore dentro data solo per le due contrassegnate come rifiutate al salvataggio; la creazione restituisce inoltre required per una categoria che non gestisce. Le altre arrivano dalla pubblicazione o dall’endpoint di convalida. La pubblicazione restituisce l’elenco completo, avvisi compresi, e quindi indica anche regole che non hanno causato il rifiuto. Basi il codice sulla regola, mai sul messaggio.

required

impedisce la pubblicazione

Il campo è obbligatorio per questa categoria ed è arrivato vuoto, assente o come elenco vuoto. Anche creare un passaporto in una categoria che non gestiamo restituisce questa regola, sul JSON Pointer /category.

Come correggereInvii un valore. Un campo url che documenta un file è soddisfatto anche allegando quel documento.

type_array

impedisce la pubblicazionerifiutato anche al salvataggio

Il campo contiene un elenco e il valore non lo era: di solito è un elenco inviato come stringa JSON.

Come correggereInvii un vero array JSON, non una stringa che lo contiene.

type_array_items

impedisce la pubblicazionerifiutato anche al salvataggio

Il campo contiene un elenco di valori di testo semplice e almeno una voce era un oggetto, un numero o un booleano.

Come correggereInvii ogni voce come stringa. Il campo riporta item_type nello schema di categoria quando lo richiede.

type_number

impedisce la pubblicazione

Il campo contiene un numero e il valore non lo era: di solito è un numero inviato come stringa.

Come correggereInvii un numero JSON, senza virgolette.

type_text

impedisce la pubblicazione

Il campo contiene testo e il valore non lo era: il più delle volte un numero, un booleano o un elenco inviati per un campo che lo schema di categoria dichiara come testo, oppure per un campo a scelta che accetta anche una risposta libera.

Come correggereInvii il valore come stringa JSON. Consulti type sul campo nello schema di categoria. Anche un select che offre un'opzione other accetta la risposta libera come stringa.

number_min

impedisce la pubblicazione

Il valore è inferiore al numero più piccolo che il campo accetta.

Come correggereLegga min sul campo nello schema di categoria e invii un valore pari o superiore.

number_max

impedisce la pubblicazione

Il valore è superiore al numero più grande che il campo accetta.

Come correggereLegga max sul campo nello schema di categoria e invii un valore pari o inferiore.

format_date

impedisce la pubblicazione

Il valore non è una data ISO 8601 valida. Una data che non esiste, come 2025-02-30, viene rifiutata qui.

Come correggereInvii YYYY-MM-DD oppure una marca temporale ISO 8601 in UTC, che termina con Z. Uno scostamento che porta la marca temporale su un'altra data viene rifiutato.

format_url

impedisce la pubblicazione

Il valore non è un URL valido.

Come correggereInvii un URL assoluto con https:// o http://.

invalid_option

impedisce la pubblicazione

Il campo accetta un insieme fisso di valori e il valore non era tra questi. Un campo che offre un'opzione other fa eccezione: memorizza testo libero.

Come correggereLegga options sul campo nello schema di categoria e invii una delle voci value elencate.

format_gtin

impedisce la pubblicazione

Il GTIN non è reale: è arrivato come stringa vuota, contiene caratteri che non sono cifre, ha la lunghezza errata, ha una cifra di controllo che non corrisponde oppure è un esempio di documentazione.

Come correggereInvii un GTIN-8, GTIN-12, GTIN-13 o GTIN-14 che GS1 le ha assegnato. Il messaggio indica quale problema si è verificato.

format_eori

impedisce la pubblicazione

Il numero EORI non corrisponde al formato che il campo accetta.

Come correggereInvii due lettere maiuscole del paese, poi da 1 a 15 lettere maiuscole o cifre. Le minuscole vengono rifiutate.

format_country_code

impedisce la pubblicazione

Il paese non è composto da due lettere maiuscole. Un codice in minuscolo come de viene rifiutato.

Come correggereInvii un codice ISO 3166-1 alpha-2 in maiuscolo, per esempio DE.

format_commodity_code

avviso

Il codice merce non corrisponde al formato SA, NC o TARIC.

Come correggereInvii 6, 8 o 10 cifre. Può anche pubblicare il passaporto con il valore così com'è.

format_email

impedisce la pubblicazione

Il valore non è un indirizzo email valido.

Come correggereInvii un indirizzo completo.

category_exists

impedisce la pubblicazione

Il passaporto indica una categoria di prodotto che questa API non gestisce.

Come correggereInviare un'altra categoria non risolve questo caso: il passaporto salvato indica una categoria che non gestiamo più. Lo ricrei in una categoria restituita dall'endpoint che elenca le categorie.

Altre tre cose portano un nome di regola. Una categoria di prodotto aggiunge regole proprie, che leggono più campi insieme: per esempio percentuali di materiali la cui somma deve essere 100. Un endpoint segnala allo stesso modo un problema nella richiesta stessa, con nomi come not_writable. E il controllo di pubblicazione riusa required per un valore che la pubblicazione richiede, per esempio un GTIN, su un campo che la categoria stessa non esige. In ogni caso il messaggio nella risposta spiega la regola.

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

200

Il passaporto contiene asserzioni ambientali, rilevate nella sua formulazione o in campi che il marchio ha contrassegnato come informazioni ambientali. 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.