Error reference

Structured error responses and how to handle them

The Particle API returns structured error responses following RFC 9457 (Problem Details for HTTP APIs). Every error includes machine-readable fields for programmatic handling and human-readable fields for display.

Error response format

{
  "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 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

no_active_plan

No billing plan selected.

billing_info_required

Payment method needed for paid plans.

plan_required

A plan is required before creating projects.

payment_past_due

Payment is overdue.

subscription_suspended

Subscription suspended for non-payment.

subscription_inactive

Subscription is not active.

subscription_not_found

Billing subscription missing.

no_active_subscription

No subscription exists for spend limit configuration.

plan_not_selected

A plan must be selected before performing this action.

plan_does_not_support_overage_usage

Current plan does not allow usage beyond included limits.

Usage limits

spend_limit_exceeded

Monthly budget cap reached.

credits_depleted

Credit balance exhausted.

rate_limit_exceeded

Too many requests — rate limit exceeded.

Authentication & authorization

auth_required

No valid authentication provided.

api_key_required

No valid API key provided.

payment_required

Keyless request to a billable endpoint — pay per request with x402 or use an API key.

pro_required

Pro subscription needed.

not_a_member

Not a member of the organization.

Account

email_exists

Account already exists with this email.

token_invalid

Reset token is invalid.

token_expired

Reset token has expired.

social_login_only

Account uses social login.

invite_expired

Organization invite has expired.

email_verification_required

Email verification required to complete registration.

Generic

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

bad_request

Request was malformed or unparseable.

validation_error

Request body or parameters failed schema validation.

not_found

Requested resource does not exist or is not accessible.

unresolved_reference

A slug or ID filter matched nothing — resolve it before filtering on it.

conflict

Request conflicts with the current state of the resource.

forbidden

Authenticated caller is not permitted to perform this action.

internal_error

Unexpected server error — retry, and contact support if it persists.

Internal

feature_check_failed

Feature availability check failed.