> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dentalspace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentazione di dentalspace. Il testo completo, incluso il riferimento API, è in /llms-full.txt. Per endpoint, campi e codici di errore la fonte di verità è openapi.json: non usare endpoint o campi non documentati.

# Errori

> Formato della risposta di errore, codici HTTP, codici errore e motivi più comuni.

L'API usa gli status HTTP standard: `2xx` successo, `4xx` errore nella richiesta, `5xx` errore del server.

## Formato

Tutti gli errori, su tutti gli endpoint, hanno questa forma:

```json theme={null}
{
  "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 |

## Codici

| 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](/api/idempotenza) |
| `429` | `rate_limited` | Troppe richieste | Aspettare i secondi di `Retry-After`. Vedi [Limiti](/api/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 |

Lo status dipende solo da `code`. I codici possibili di ogni endpoint sono nella sua pagina.

## Motivi più comuni

`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](/api/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 |

I motivi specifici di un endpoint, come `redeliver_limit` o `stripe_error`, sono descritti nella sua pagina.

## Esiti negativi con `200`

Alcuni endpoint rispondono a una domanda: un «no» è una risposta, non un errore.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.