# API envelopes

> The yalla.output.v1 and yalla.error.v1 envelopes every response uses.

Every Yalla API response is wrapped in a stable, versioned envelope. Parse the envelope defensively and treat unknown `schema` versions as a compatibility warning.

## Success envelope

**yalla.output.v1**

```json
{
  "schema": "yalla.output.v1",
  "request_id": "req_01HZY…",
  "data": { "deployment_id": "dep_01HZY…", "status": "deploying" }
}
```

## Error envelope

**yalla.error.v1**

```json
{
  "schema": "yalla.error.v1",
  "request_id": "req_01HZY…",
  "error": { "code": "E_RATE_LIMITED", "message": "Too many requests", "hint": "Retry after the reset window." }
}
```

Always surface `request_id` in error UI and support requests. See [error codes](/docs/error-codes) for the full catalog.