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

# Errors

> Handle structured StoreInspect API errors.

Error responses use a stable JSON envelope.

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "param": "filters",
    "request_id": "req_abc123"
  }
}
```

## Status codes

| Status | Meaning                                                                   |
| ------ | ------------------------------------------------------------------------- |
| `400`  | Invalid request body, query parameter, cursor, ID, or filter combination. |
| `401`  | Missing, invalid, or revoked API key.                                     |
| `402`  | Not enough contact credits for a reveal request.                          |
| `403`  | API access is not enabled for the account, plan, key, or entitlement.     |
| `404`  | The requested resource was not found.                                     |
| `409`  | Idempotency conflict or request state conflict.                           |
| `429`  | Monthly quota, search-row quota, or request rate limit exceeded.          |
| `500`  | Unexpected server error.                                                  |

## Trial credit exhaustion

If a trial user exhausts the 250 trial contact credits, reveal requests return a structured billing action.

```json theme={null}
{
  "error": {
    "type": "quota_error",
    "code": "insufficient_contact_credits",
    "message": "You have used all 250 trial contact credits. Start paid Pro now to unlock 1000 monthly credits.",
    "param": "contact_ids",
    "billing": {
      "action": "end_trial_to_unlock_pro_credits",
      "current_limit": 250,
      "paid_plan_limit": 1000,
      "trial_ends_at": "2026-07-11T01:03:57.000Z",
      "url": "https://storeinspect.com/dashboard/settings/billing"
    },
    "request_id": "req_abc123"
  }
}
```

## Support

When reporting an issue, include the `request_id` from the response body or `X-Request-Id` header.