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

# Formato delle risposte

> Come sono strutturate le risposte dell'API Wappfy — l'envelope standard, la paginazione e il formato degli errori.

# Formato delle risposte

Tutte le risposte dell'API Wappfy seguono un formato envelope coerente.

## Risposte di successo

Ogni risposta di successo e racchiusa in un oggetto standard:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-10T12:00:00.000Z"
  }
}
```

| Campo            | Tipo              | Descrizione                                         |
| ---------------- | ----------------- | --------------------------------------------------- |
| `success`        | `boolean`         | Sempre `true` per le risposte di successo           |
| `data`           | `object \| array` | Il payload della risposta                           |
| `meta.requestId` | `string`          | Identificatore univoco della richiesta per il debug |
| `meta.timestamp` | `string`          | Timestamp in formato ISO 8601                       |

## Risposte paginate

Gli endpoint che restituiscono liste includono metadati di paginazione:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [ ... ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  },
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2026-02-10T12:00:00.000Z"
  }
}
```

Usa i parametri query `page` e `limit` per controllare la paginazione:

```bash theme={null}
GET /api/instances?page=2&limit=10
```

## Risposte di errore

Le richieste fallite restituiscono un oggetto errore:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance with ID abc123 not found",
    "details": {}
  },
  "meta": {
    "requestId": "req_ghi789",
    "timestamp": "2026-02-10T12:00:00.000Z"
  }
}
```

### Codici di errore comuni

| Stato HTTP | Codice                | Descrizione                                             |
| ---------- | --------------------- | ------------------------------------------------------- |
| `400`      | `VALIDATION_ERROR`    | Il corpo della richiesta non ha superato la validazione |
| `401`      | `UNAUTHORIZED`        | Token di autenticazione mancante o non valido           |
| `403`      | `FORBIDDEN`           | Permessi insufficienti                                  |
| `404`      | `NOT_FOUND`           | La risorsa non esiste                                   |
| `409`      | `PLAN_LIMIT_REACHED`  | Limite di istanze raggiunto per il tuo piano            |
| `429`      | `RATE_LIMIT_EXCEEDED` | Troppe richieste                                        |
| `500`      | `INTERNAL_ERROR`      | Errore interno del server                               |

<Note>
  Il campo `meta.requestId` e utile per le richieste di supporto — includilo quando contatti l'assistenza per un debug piu rapido.
</Note>