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

# Response envelope

> Every Financial Data API response shares one predictable JSON shape: data plus meta.

Every response from the Financial Data API shares one shape. There is exactly one envelope. Whether you request a list or a single item, you read the payload from `data` and the bookkeeping from `meta`. You never have to special-case the parsing logic per endpoint.

This page describes the envelope, every `meta` field, and how the request identifier flows through both successful and error responses for tracing.

## The two payload shapes

`data` is the only field whose type varies, and it varies in exactly one way:

* **List responses** put an array in `data`. List responses are the ones that paginate, so their `meta` carries a `pagination` block.
* **Item responses** put a single object in `data`. Item responses describe one resource (for example one country, one entity, or one provenance chain) and do not paginate.

Everything else (the `meta` block, the top-level `requestId`) is identical across both.

<CodeGroup>
  ```json List response theme={"theme":"css-variables"}
  {
    "data": [
      {
        "indicator": "cpi_inflation_yoy",
        "country": "USA",
        "value": 3.2,
        "period": "2026-05",
        "freshness": "fresh"
      }
    ],
    "meta": {
      "request_id": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
      "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
      "api_version": "v1",
      "pagination": {
        "limit": 100,
        "cursor": null,
        "next_cursor": null,
        "has_more": false
      }
    },
    "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55"
  }
  ```

  ```json Item response theme={"theme":"css-variables"}
  {
    "data": {
      "indicator": "cpi_inflation_yoy",
      "country": "USA",
      "value": 3.2,
      "period": "2026-05",
      "freshness": "fresh"
    },
    "meta": {
      "request_id": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
      "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
      "api_version": "v1"
    },
    "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55"
  }
  ```
</CodeGroup>

<Note>
  Only list responses include `meta.pagination`. Item responses omit it because there is nothing to page through.
</Note>

## Top-level fields

<ResponseField name="data" type="array | object" required>
  The response payload. An array for list endpoints, a single object for item endpoints. This is the only field whose type changes between response kinds.
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata: the request identifier, the API version, and (on list responses) the pagination block. See below.
</ResponseField>

<ResponseField name="requestId" type="string" required>
  The request identifier, repeated at the top level for convenience. Identical to `meta.request_id` and `meta.requestId`. Quote this value when you contact support.
</ResponseField>

## The `meta` block

<ResponseField name="meta.request_id" type="string" required>
  A UUID that uniquely identifies this request on the server. Logged server-side, so it lets support trace exactly what your call did.
</ResponseField>

<ResponseField name="meta.requestId" type="string" required>
  The same UUID as `meta.request_id`, provided in camelCase as well so clients in either naming convention can read it without transformation.
</ResponseField>

<ResponseField name="meta.api_version" type="string" required>
  The API version that served the response. Always `"v1"` for the current surface. Paths are versionless; this field reports the underlying API version.
</ResponseField>

<ResponseField name="meta.pagination" type="object">
  Present on list responses only. Carries the cursor state for paging through results. See the [Pagination](/concepts/pagination) page for the full loop.

  <Expandable title="pagination fields" defaultOpen={true}>
    <ResponseField name="limit" type="integer">
      The page size that was applied to this request (1 to 500, default 100).
    </ResponseField>

    <ResponseField name="cursor" type="string | null">
      The opaque cursor you supplied for this page, or `null` on the first page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      The cursor to pass on your next request to fetch the following page. `null` when there are no more pages.
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      `true` if more pages exist. Keep requesting with `next_cursor` while this is `true`.
    </ResponseField>
  </Expandable>
</ResponseField>

## The request identifier

Both successful and error responses carry the same identifier in three places: `meta.request_id`, `meta.requestId`, and the top-level `requestId`. They always hold the same value within one response. The redundancy exists so you can read the identifier whether your code expects snake\_case or camelCase, and whether it inspects the envelope root or the `meta` block.

Capture it on every response, including errors. It is the fastest way for support to find your request in the logs.

```ts Capturing the request id (TypeScript) theme={"theme":"css-variables"}
const res = await fetch(
  "https://api.financialdatapi.com/observations?country=USA&indicator=cpi_inflation_yoy",
  { headers: { "x-api-key": process.env.FINANCIALDATA_API_KEY! } },
);
const body = await res.json();
console.log("request id:", body.requestId);
```

## Error responses

Errors use a sibling envelope: `error` replaces `data`, and the request identifier is preserved so failures stay traceable. See the [Errors](/concepts/errors) page for the full shape and the code table.

```json Error envelope theme={"theme":"css-variables"}
{
  "error": {
    "code": "bad_request",
    "message": "Unknown query parameter: 'contry'",
    "request_id": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55",
    "details": {}
  },
  "requestId": "8f1c2e90-7a4b-4c3d-9e21-2b6f0a1c4d55"
}
```

<Columns cols={2}>
  <Card title="Pagination" icon="arrow-right-arrow-left" href="/concepts/pagination">
    Follow `next_cursor` while `has_more` is true.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/concepts/errors">
    The error envelope and the full code table.
  </Card>
</Columns>