Skip to main content
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)

FieldTypeDescription
typestringURI linking to this error’s documentation page.
titlestringShort, static summary (e.g. “Payment Required”). Does not change between occurrences.
statusintegerHTTP status code.
detailstringHuman-readable explanation of what went wrong.

​
Extension fields

FieldTypeDescription
error_codestringStable, machine-readable identifier. Use this for programmatic branching.
resolveobjectActionable resolution guidance. Omitted when no self-service fix exists.

​
Resolve object

FieldTypeDescription
messagestringHuman-readable call-to-action (e.g. “Select a billing plan to continue.”).
urlstringDeep link into the where a human can fix the issue.
actionstringMachine-readable action type for agents (e.g. select_plan).
methodstringHTTP method for the resolution endpoint.
endpointstringAPI 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.

​
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.

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.

​
Internal

feature_check_failed

Feature availability check failed.