Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Formato della risposta di errore, codici HTTP, codici errore e motivi più comuni.
2xx successo, 4xx errore nella richiesta, 5xx errore del server.
{
"error": {
"code": "invalid_request",
"message": "Richiesta non valida: guarda details.issues.",
"details": {
"in": "body",
"issues": [{ "path": "start", "message": "Invalid ISO datetime" }]
},
"requestId": "req_6f1c2a0e4b8d4c6e9a512f3b7d8e9a10"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
error.code | string | Codice stabile. Usalo nella logica del tuo programma |
error.message | string | Spiegazione in italiano per una persona. Può cambiare: non confrontarla nel codice |
error.details | object | null | Dati aggiuntivi, per esempio il campo sbagliato o il motivo (reason) |
error.requestId | string | Uguale all’header X-Request-Id. Citalo all’assistenza |
| Status | code | Causa | Cosa fare |
|---|---|---|---|
400 | invalid_request | Parametri, corpo o percorso non validi. details.in dice dove (path, query, body), details.issues campo per campo | Correggere la richiesta |
401 | unauthenticated | Header Authorization assente | Mandare Authorization: Bearer dsk_live_... |
401 | api_key_invalid | Chiave sconosciuta o malformata | Controllare la chiave |
401 | api_key_revoked | Chiave revocata, sostituita o scaduta | Non ripetere. Creare una nuova chiave |
403 | plan_required | La clinica non ha il piano Clinic attivo | Non ripetere |
403 | insufficient_scope | La chiave non ha lo scope dell’endpoint. details.requiredScopes elenca quelli che mancano | Usare una chiave con quello scope |
403 | forbidden | Operazione non permessa per una regola della clinica. Vedi details.reason | Non ripetere |
404 | not_found | La risorsa non esiste, è di un’altra clinica o di una sede che la chiave non vede | Controllare gli id |
409 | no_availability | L’orario non è più prenotabile. details.reason e details.alternatives | Proporre un altro orario |
409 | conflict | La richiesta urta lo stato attuale della risorsa. Vedi details.reason | Rileggere la risorsa e decidere |
409 | idempotency_in_progress | Una richiesta con la stessa Idempotency-Key è ancora in corso | Ripetere dopo qualche secondo con la stessa chiave |
422 | idempotency_key_reused | La Idempotency-Key è già stata usata per un’altra operazione, un altro corpo o un’altra chiave API | Usare una chiave nuova. Vedi Idempotenza |
429 | rate_limited | Troppe richieste | Aspettare i secondi di Retry-After. Vedi Limiti |
500 | internal_error | Errore del server | Ripetere. Se continua, segnalarlo con il requestId |
503 | unavailable | Un servizio necessario non risponde | Ripetere dopo qualche secondo |
code. I codici possibili di ogni endpoint sono nella sua pagina.
details.reason spiega un 403 forbidden o un 409. I principali:
reason | Codice | Significato |
|---|---|---|
version_mismatch | 409 conflict | La risorsa è cambiata dopo che l’hai letta (If-Match). Rileggila e riprova |
concurrent_request | 409 conflict | Un’altra richiesta sta creando la stessa persona (stesso telefono o email). Riprova: troverai quella creata |
duplicate_patient | 409 conflict | Esiste già un paziente con lo stesso nome e lo stesso telefono o email. details.patientId è il suo id |
response_not_stored | 409 conflict | La prima risposta conteneva un segreto mostrato una volta e non è stata conservata. Vedi Idempotenza |
slot_taken | 409 no_availability | L’orario è stato preso nel frattempo |
plan_limit | 403 forbidden | Il piano ha raggiunto il numero massimo di pazienti |
ai_disabled | 403 forbidden | La clinica ha spento l’elaborazione AI: l’agente vocale non è disponibile |
redeliver_limit o stripe_error, sono descritti nella sua pagina.
200| Endpoint | Condizione | Risposta |
|---|---|---|
GET /patients/lookup | Nessuno con quel numero | 200 con found: false |
GET /calendars/{id}/availability | Nessun orario libero | 200 con data: []. window: null se le regole del calendario non lasciano niente da cercare |