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

# Response Format

> Every API response follows a consistent JSON envelope.

Every response from the NGN Market API follows the same JSON structure whether the request succeeds or fails. This means you can write one response-handling layer in your application and rely on the same fields being present for every endpoint.

## Successful response

```json theme={null}
{
  "success": true,
  "data": { },
  "meta": {
    "plan": "starter",
    "calls_used": 4821,
    "calls_remaining": 95179,
    "reset_at": "2026-05-01T00:00:00.000Z"
  }
}
```

### Top-level fields

| Field     | Type            | Description                                                                       |
| :-------- | :-------------- | :-------------------------------------------------------------------------------- |
| `success` | boolean         | `true` on success, `false` on error                                               |
| `data`    | object \| array | The endpoint payload. Shape varies, see individual endpoint pages.                |
| `meta`    | object          | Quota state for your account. Present on every successful authenticated response. |

### The `meta` object

| Field             | Type    | Description                                                                 |
| :---------------- | :------ | :-------------------------------------------------------------------------- |
| `plan`            | string  | Your current plan: `free`, `starter`, `growth`, `business`, or `enterprise` |
| `calls_used`      | integer | Total calls made this calendar month across all your keys                   |
| `calls_remaining` | integer | Calls left before your quota is exhausted                                   |
| `reset_at`        | string  | ISO 8601 UTC timestamp. Always the 1st of next month at midnight UTC.       |

<Tip>
  Check `meta.calls_remaining` in your app so you can detect when you are close to your limit before hitting it.
</Tip>

## Error response

When a request fails, `success` is `false` and the response includes an `error` object instead of `data`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "This endpoint requires a starter plan or higher.",
    "required_plan": "starter",
    "current_plan": "free"
  }
}
```

### Error object fields

| Field           | Type   | Description                                                                        |
| :-------------- | :----- | :--------------------------------------------------------------------------------- |
| `code`          | string | Machine-readable error identifier. Use this to branch error handling in your code. |
| `message`       | string | Human-readable description of what went wrong.                                     |
| `required_plan` | string | *(PLAN\_REQUIRED only)* Minimum plan needed to access this endpoint.               |
| `current_plan`  | string | *(PLAN\_REQUIRED only)* Your account's current plan.                               |

<Note>
  The `QUOTA_EXCEEDED` error (`429`) includes both an `error` object and a `meta` object so you can still read your quota state when you are over the limit. See [Rate limits](/rate-limits) for the full example.
</Note>

## Handling responses in code

Check `success` first, then branch on `error.code` for specific handling:

```javascript theme={null}
const res = await fetch('https://api.ngnmarket.com/v1/market/snapshot', {
  headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }
});

const body = await res.json();

if (!body.success) {
  if (body.error.code === 'QUOTA_EXCEEDED') {
    console.warn('Quota exhausted. Resets at:', body.meta.reset_at);
  } else if (body.error.code === 'PLAN_REQUIRED') {
    console.error(`Upgrade to ${body.error.required_plan} to use this endpoint.`);
  } else {
    console.error('API error:', body.error.message);
  }
} else {
  // body.data contains the endpoint payload
  console.log('Remaining calls:', body.meta.calls_remaining);
}
```

For a full list of error codes and how to resolve each one, see [Errors](/errors).