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

# Error reference

> Structured error responses and how to handle them

export const DashboardLink = ({children}) => {
  return <a href="https://platform.particle.pro/dashboard">{children}</a>;
};

The Particle API returns structured error responses following [RFC 9457 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc9457). Every error includes machine-readable fields for programmatic handling and human-readable fields for display.

## Error response format

```json theme={"dark"}
{
  "type": "https://docs.particle.pro/errors/no_active_plan",
  "title": "Payment Required",
  "status": 402,
  "detail": "No active billing plan.",
  "error_code": "no_active_plan",
  "resolve": {
    "message": "Select a billing plan to continue.",
    "url": "https://platform.particle.pro/organizations/{orgId}/billing",
    "action": "select_plan",
    "method": "POST",
    "endpoint": "/v1/organizations/{orgId}/billing/subscription"
  }
}
```

### Standard fields (RFC 9457)

| Field    | Type    | Description                                                                           |
| -------- | ------- | ------------------------------------------------------------------------------------- |
| `type`   | string  | URI linking to this error's documentation page.                                       |
| `title`  | string  | Short, static summary (e.g. "Payment Required"). Does not change between occurrences. |
| `status` | integer | HTTP status code.                                                                     |
| `detail` | string  | Human-readable explanation of what went wrong.                                        |

### Extension fields

| Field        | Type   | Description                                                               |
| ------------ | ------ | ------------------------------------------------------------------------- |
| `error_code` | string | Stable, machine-readable identifier. Use this for programmatic branching. |
| `resolve`    | object | Actionable resolution guidance. Omitted when no self-service fix exists.  |

### Resolve object

| Field      | Type   | Description                                                                                    |
| ---------- | ------ | ---------------------------------------------------------------------------------------------- |
| `message`  | string | Human-readable call-to-action (e.g. "Select a billing plan to continue.").                     |
| `url`      | string | Deep link into the <DashboardLink>platform UI</DashboardLink> where a human can fix the issue. |
| `action`   | string | Machine-readable action type for agents (e.g. `select_plan`).                                  |
| `method`   | string | HTTP method for the resolution endpoint.                                                       |
| `endpoint` | string | API path an agent can call to fix the issue.                                                   |

## Handling errors

### For UI clients

1. Switch on `error_code` to render the appropriate component or message.
2. Use `resolve.url` to link the user to the relevant platform page.
3. Fall back to displaying `detail` if the `error_code` is unrecognized.

### For agents and SDKs

1. Switch on `error_code` to decide the remediation path.
2. Use `resolve.action` as a semantic intent (e.g. `select_plan`, `contact_support`).
3. Call `resolve.method` + `resolve.endpoint` to fix the issue programmatically.
4. Dereference `type` for documentation on the specific error.

## Error codes by category

### Billing & subscription

<CardGroup cols={2}>
  <Card title="no_active_plan" icon="credit-card" href="/errors/no_active_plan">
    No billing plan selected.
  </Card>

  <Card title="billing_info_required" icon="credit-card" href="/errors/billing_info_required">
    Payment method needed for paid plans.
  </Card>

  <Card title="plan_required" icon="credit-card" href="/errors/plan_required">
    A plan is required before creating projects.
  </Card>

  <Card title="payment_past_due" icon="clock" href="/errors/payment_past_due">
    Payment is overdue.
  </Card>

  <Card title="subscription_suspended" icon="ban" href="/errors/subscription_suspended">
    Subscription suspended for non-payment.
  </Card>

  <Card title="subscription_inactive" icon="ban" href="/errors/subscription_inactive">
    Subscription is not active.
  </Card>

  <Card title="subscription_not_found" icon="magnifying-glass" href="/errors/subscription_not_found">
    Billing subscription missing.
  </Card>

  <Card title="no_active_subscription" icon="magnifying-glass" href="/errors/no_active_subscription">
    No subscription exists for spend limit configuration.
  </Card>

  <Card title="plan_not_selected" icon="credit-card" href="/errors/plan_not_selected">
    A plan must be selected before performing this action.
  </Card>

  <Card title="plan_does_not_support_overage_usage" icon="gauge-max" href="/errors/plan_does_not_support_overage_usage">
    Current plan does not allow usage beyond included limits.
  </Card>
</CardGroup>

### Usage limits

<CardGroup cols={2}>
  <Card title="spend_limit_exceeded" icon="gauge-max" href="/errors/spend_limit_exceeded">
    Monthly budget cap reached.
  </Card>

  <Card title="credits_depleted" icon="gauge-max" href="/errors/credits_depleted">
    Credit balance exhausted.
  </Card>

  <Card title="rate_limit_exceeded" icon="gauge-max" href="/errors/rate_limit_exceeded">
    Too many requests — rate limit exceeded.
  </Card>
</CardGroup>

### Authentication & authorization

<CardGroup cols={2}>
  <Card title="auth_required" icon="lock" href="/errors/auth_required">
    No valid authentication provided.
  </Card>

  <Card title="api_key_required" icon="key" href="/errors/api_key_required">
    No valid API key provided.
  </Card>

  <Card title="pro_required" icon="star" href="/errors/pro_required">
    Pro subscription needed.
  </Card>

  <Card title="not_a_member" icon="user-slash" href="/errors/not_a_member">
    Not a member of the organization.
  </Card>
</CardGroup>

### Account

<CardGroup cols={2}>
  <Card title="email_exists" icon="envelope" href="/errors/email_exists">
    Account already exists with this email.
  </Card>

  <Card title="token_invalid" icon="link-slash" href="/errors/token_invalid">
    Reset token is invalid.
  </Card>

  <Card title="token_expired" icon="hourglass-end" href="/errors/token_expired">
    Reset token has expired.
  </Card>

  <Card title="social_login_only" icon="google" href="/errors/social_login_only">
    Account uses social login.
  </Card>

  <Card title="invite_expired" icon="envelope-open" href="/errors/invite_expired">
    Organization invite has expired.
  </Card>

  <Card title="email_verification_required" icon="envelope" href="/errors/email_verification_required">
    Email verification required to complete registration.
  </Card>
</CardGroup>

### Generic

These codes are returned when a more specific code does not apply — typically for request validation, missing resources, and unexpected failures.

<CardGroup cols={2}>
  <Card title="bad_request" icon="circle-exclamation" href="/errors/bad_request">
    Request was malformed or unparseable.
  </Card>

  <Card title="validation_error" icon="circle-exclamation" href="/errors/validation_error">
    Request body or parameters failed schema validation.
  </Card>

  <Card title="not_found" icon="magnifying-glass" href="/errors/not_found">
    Requested resource does not exist or is not accessible.
  </Card>

  <Card title="conflict" icon="code-merge" href="/errors/conflict">
    Request conflicts with the current state of the resource.
  </Card>

  <Card title="forbidden" icon="lock" href="/errors/forbidden">
    Authenticated caller is not permitted to perform this action.
  </Card>

  <Card title="internal_error" icon="server" href="/errors/internal_error">
    Unexpected server error — retry, and contact support if it persists.
  </Card>
</CardGroup>

### Internal

<CardGroup cols={2}>
  <Card title="feature_check_failed" icon="server" href="/errors/feature_check_failed">
    Feature availability check failed.
  </Card>
</CardGroup>