Documentation
DocumentationErrors & response envelope
DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY

Errors & response envelope

Machine-readable error codes, retryability flags and 207 Multi-Status envelopes.

ONE GATEWAYCoordinates → eligible provider → canonical responseWhy UWA
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.

Search local documentation. No external requests.

↑↓ to move · Enter to openESC to close