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

# Errors and compatibility

> Machine-readable failures, limits and retry rules.

REST errors contain a stable machine-readable `error` string, with optional `message` and validation `issues`. Never parse human-readable message text to decide what to do.

| HTTP status | Meaning | Client action |
| - | - | - |
| `400` | Malformed JSON, empty body, or invalid query parameters | Correct the request. |
| `402` | A new acquisition needs payment; the `WWW-Authenticate: Payment` header carries the MPP challenge | Pay and retry with `Authorization: Payment`. Keep the same credential for any retry. |
| `404` | Dataset/tile/request absent or not publicly accessible | Inspect the catalog; do not infer private data existence. |
| `413` | Request, row count, date range, or response exceeds a bound | Narrow the query or page size. |
| `415` | Incorrect media type on a query POST | Send `Content-Type: application/json`. |
| `422` | Invalid schema, unsupported/incomplete query, or an acquisition the source cannot satisfy (`outside_source_coverage`, `no_cell_centers`, `variable_unavailable`, `dataset_version_pinned`) | Inspect issues or call coverage resolution. |
| `502` | `payment_or_fulfillment_failed` | Retry with the same payment credential: it recovers the request without a second charge. |
| `503` | Data service unavailable | Back off with a bounded retry count. |

Coverage resolution returns `200` even when `available` is false. Its `reason` is one of `coverage_unavailable`, `request_too_large`, `no_cell_centers`, or `unsupported_grid`, and `acquisitionEnabled` says whether `/api/v1/data/requests` can acquire the miss. No result is silently truncated to make the query succeed.

An acquisition that fails is reported by `GET /api/v1/data/requests/{id}` with `status: "failed"` and `error.reason`. Submitting the same request again within 15 minutes returns that failure; after that it starts a new acquisition.

Reads and direct queries have no purchase side effects. Retry transient failures with exponential backoff and a bounded retry count. Payment retries are idempotent per credential; never create a second payment for a request whose first payment may have succeeded. A paid acquisition that fails is refunded.

The `/api/v1` path defines the major version. Clients should accept additive response fields and inspect capabilities for new operations. Removing or changing the meaning of a documented field requires a new major contract. Stable published dataset IDs can be pinned across API calls. The specification's `info.version` identifies the contract release.

MCP tools return structured JSON and mark failures with `isError`. Tool descriptions and input schemas use the same contract as REST. They never expose infrastructure credentials or raw database error details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.