Errors, limits, and CORS

Structured errors

{
  "error": {
    "code": "provider_timeout",
    "message": "USDA Soil Data Access timed out. Try again later.",
    "request_id": "6c1ccbbf-20e0-41e9-948f-7bc876f85adc",
    "provider": "usda_sda",
    "retryable": true
  }
}

HTTP	Typical meaning
404	Route does not exist
414	Query string exceeds 1,024 characters
422	Invalid location/depth/property or provider lacks an adapter
429	Rate limit exceeded; respect Retry-After
502	Provider unavailable, invalid, or returned an upstream error
504	Provider timed out

Every response includes X-Request-ID. A caller may supply a 1–64 character X-Request-ID using letters, numbers, dots, underscores, or hyphens; other values are replaced.

Limits

The application permits 120 requests per minute per client by default. Nginx adds a separate short-burst boundary. Provider queries use a 10-second timeout, one limited retry for transient connection or 5xx failures, a maximum of one provider and eight properties, a 0–200 cm depth range, and a bounded upstream row count.

Limits are operational controls, not a service-level guarantee, and may change during the experimental period.

Cache behavior

Successful provider payloads use a bounded six-hour in-process cache. Expired entries are never silently returned after a provider failure. Every normalized and raw response reports hit state, storage timestamp, and age. The retrieval time equals the upstream fetch time represented by the cache entry.

CORS

Production returns Access-Control-Allow-Origin: * for this anonymous, read-only API and does not allow credentials. This deliberate exception lets independent D3 dashboards, static websites, and teaching tools request public records directly. Allowed methods are GET and OPTIONS; there are no authenticated browser mutations on this origin.

If future routes accept credentials or modify state, they will use a separate explicit origin allowlist rather than inherit this policy.

Retry guidance

Retry only when retryable is true. Use exponential backoff and jitter, stop after a small number of attempts, and retain the request ID for debugging. Do not repeatedly retry a validation error or unsupported provider.