DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY
Errors & response envelope
Machine-readable error codes, retryability flags and 207 Multi-Status envelopes.
On this page 3 sections
#Single-category response convention
Successful capability responses contain data and meta. Failure responses follow a structured error envelope with a machine-readable code, correlated request_id, HTTP status and retryable boolean.
{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "API key lacks the required scope",
"request_id": "req_01J...",
"retryable": false
}
}#Multi-category 207 Multi-Status envelope
On GET /v1/datasets, if some requested categories succeed and others fail, UWA returns HTTP 207 Multi-Status with meta.partial=true, preserving every successful dataset alongside per-category error details:
{
"data": {
"weather": { "data": { "schema_version": "weather.v1", "...": "..." }, "meta": { "provider": "openweather" } }
},
"errors": {
"astronomy": { "status": 503, "error": { "code": "PROVIDER_NOT_AVAILABLE", "retryable": true } }
},
"meta": {
"request_id": "req_01J...",
"timestamp": "2026-11-18T04:30:00Z",
"partial": true
}
}#Failure interpretation
Distinguish non-retryable client/policy errors (400 INVALID_LOCATION, 401 UNAUTHORIZED, 403 FORBIDDEN) from retryable infrastructure or upstream failures (503 AUTH_BACKEND_UNAVAILABLE with Retry-After: 1, 503 PROVIDER_NOT_AVAILABLE).
Canonical contracts:
docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.