{ }nido · developers
← Panoramica

Errori

Ogni errore ha lo stesso formato: type per la categoria (e lo status HTTP), code stabile da gestire nel codice, param per il campo coinvolto e request_id da citare al supporto.

Error.json
{
  "error": {
    "type": "validation_error",
    "code": "invalid_property",
    "message": "Email non valida",
    "param": "email",
    "doc_url": "…/developers/errors#invalid_property",
    "request_id": "req_9f2c11ab"
  }
}
400

Richiesta non valida

invalid_request

La richiesta è malformata: JSON non valido, metodo non supportato o parametro incompatibile.

invalid_jsonIl corpo della richiesta non è JSON valido.Come risolvere: Invia `Content-Type: application/json` e un oggetto JSON.
method_not_allowedIl percorso esiste ma non con questo metodo HTTP.Come risolvere: Controlla il metodo nella reference.
401

Autenticazione

authentication_error

Manca il token o non è valido. Usa `Authorization: Bearer nido_sk_live_…` o un token OAuth.

unauthenticatedNessuna credenziale nella richiesta.Come risolvere: Aggiungi l'header Authorization.
invalid_api_keyLa chiave API non esiste, è stata revocata o è scaduta.Come risolvere: Crea una nuova chiave in Webhook & API → Chiavi API.
invalid_tokenIl token OAuth è scaduto, ha un'audience errata o non è firmato da Nido.Come risolvere: Rinnova il token con il refresh token.
403

Permessi

permission_error

Il token è valido ma non ha lo scope richiesto, oppure il ruolo dell'utente non lo consente.

missing_scopeIl token non include lo scope richiesto dall'endpoint (indicato nel messaggio).Come risolvere: Crea la chiave o rinnova il consenso OAuth con lo scope necessario.
scope_not_allowedStai concedendo a una chiave permessi che non hai.
not_a_memberL'utente che ha autorizzato il client non fa più parte del workspace.
impersonation_read_onlySessione di supporto in sola lettura: le scritture sono bloccate e registrate.
two_factor_requiredIl workspace richiede l'autenticazione a due fattori per questa operazione.
owner_onlyOperazione riservata al proprietario del workspace.
ai_disabledNido AI è disattivato per il workspace.
402

Limite del piano

plan_limit

La funzione non è inclusa nel piano del workspace o hai superato una quota.

feature_not_in_planLa funzione richiede un piano superiore (es. webhook, API o MCP).Come risolvere: Aggiorna il piano in Impostazioni → Piano e fatturazione.
404

Non trovato

not_found

La risorsa non esiste nel workspace del token (o è nel cestino).

unknown_endpointIl percorso non corrisponde ad alcun endpoint di /api/v1.
resource_missingIl record indicato non esiste nel workspace del token.
409

Conflitto

conflict

La richiesta è in conflitto con lo stato attuale (duplicati, stato già raggiunto).

duplicate_emailEsiste già un contatto con questa email (deduplica case-insensitive).Come risolvere: Usa `?upsert=true` su POST /contacts per aggiornarlo.
duplicate_domainEsiste già un'azienda con questo dominio.
already_wonIl deal è già chiuso come vinto.
already_lostIl deal è già chiuso come perso.
workflow_not_activeIl workflow non è attivo: pubblicalo prima di iscrivere record.
run_not_failedSi possono riprovare solo esecuzioni fallite o annullate.
integration_coming_soonL'integrazione non è ancora disponibile.
not_connectedL'integrazione non è collegata.
409

Idempotenza

idempotency_error

La stessa `Idempotency-Key` è stata usata per una richiesta diversa nelle ultime 24 h.

idempotency_key_reusedLa chiave di idempotenza è già stata usata con un altro percorso o metodo.Come risolvere: Genera una nuova Idempotency-Key (es. UUID v4) per ogni operazione distinta.
422

Validazione

validation_error

Uno o più campi non superano la validazione: `param` indica il campo.

invalid_propertyUn campo ha un valore non valido: `param` indica quale.Come risolvere: Controlla tipo e valori ammessi nella reference dell'endpoint.
missing_propertyManca un campo obbligatorio.
missing_identityUn contatto deve avere almeno email, nome o cognome.
invalid_filterCampo o operatore non supportato in `filter[...]`.Come risolvere: Operatori: eq, ne, gt, gte, lt, lte, in, contains, empty, not_empty.
invalid_sortCampo non ordinabile in `sort`.
missing_reasonPer chiudere un deal come perso serve il motivo.
invalid_urlL'URL del webhook non è valido o usa un protocollo non ammesso.
insecure_urlIn produzione gli endpoint webhook devono usare HTTPS.
private_urlNon è possibile inviare webhook a indirizzi interni o privati.
no_stepsUn workflow senza azioni non può essere pubblicato.
invalid_stepUn passo del workflow è incompleto (URL, oggetto email…).
unknown_templateIl `template_key` non corrisponde ad alcun modello di GET /workflow-templates.
file_too_largeIl file supera la dimensione massima consentita.
too_many_rowsIl CSV supera il numero massimo di righe per un import.
429

Troppe richieste

rate_limit

Massimo 100 richieste ogni 10 secondi per token. Attendi `Retry-After` secondi.

rate_limitedHai superato 100 richieste in 10 secondi con lo stesso token.Come risolvere: Rispetta l'header Retry-After e usa backoff esponenziale.
500

Errore del server

api_error

Errore inatteso o servizio esterno non raggiungibile. Riprova con backoff; se persiste contattaci con il `request_id`.

internal_errorErrore imprevisto lato Nido.Come risolvere: Riprova; se persiste scrivi a supporto con il request_id.
maintenance_read_onlyPiattaforma in manutenzione: temporaneamente sola lettura.
provider_unreachableUn servizio esterno (email, AI, pagamenti) non risponde.
email_send_failedIl provider email ha rifiutato l'invio.