Errors - Nozle

Overview

Application Workflows

Billing Resources

Usage & Metering

Invoicing & Payments

Platform & Operations

HTTP status codes

Status	Meaning
`200`–`299`	Successful request.
`400`	Missing, invalid, or conflicting parameters.
`401`	Missing or invalid credential.
`403`	Credential lacks permission or a publishable key attempted a protected operation.
`404`	Resource was not found within the authenticated organization.
`409`	Idempotency key or resource-state conflict, such as another checkout in progress. Reload the state, then retry.
`422`	Request is syntactically valid but violates a product rule, or the resource’s current state refuses it (for example a voided invoice).
`429`	Request was rate limited.
`500`	Unexpected server error. The body is still JSON with a `code`.
`502`	A service Nozle depends on did not answer: `upstream_unavailable`. Safe to retry.
`503`	Temporary dependency, lock, or service failure.

Nozle never returns 405 for a business rule; a refused state is a 422 with a code.

Response shape

Endpoints return a short error description and may include a stable code or additional fields:

{
  "status": 422,
  "error": "Unprocessable Entity",
  "code": "not_voidable"
}

Every Core error carries status, error and code; validation errors add error_details. A malformed body is 400 with code: "bad_request". Do not parse human-readable text when a machine-readable code is available.

Retry guidance

Retry read requests only within your latency and request budget.
Retry idempotent mutations with the same idempotency key and payload.
Retry events with the same transaction ID.
Honor Retry-After when returned.
Do not retry validation, authorization, or insufficient-credit decisions without changing the underlying state.

Common failures

Match on the status and code, not on the message text.

Status and `code`	What happened	What to do
`401` (`missing authorization header`, `invalid authorization format, expected Bearer token`, `invalid api key`)	The Engine got no `Authorization` header, one that is not `Bearer <key>`, or a key it does not know or that was revoked.	Send `Authorization: Bearer sk_...` with a current key.
`403` (`publishable_key_not_allowed` from Core; a `403` message from the Engine)	A `pk_` key called something other than the plan catalog.	Call from your backend with an `sk_` key. See public plan catalog.
`404` `customer_not_found`	No customer has that ID, for example on `subscribe`.	Create the customer with `POST /customers`, then call again.
`404` `active_subscription_not_found`	`usage.check` or `usage.track` for a customer with no active subscription.	Activate a subscription for the customer.
`422` `active_subscription_ambiguous`	The customer has more than one active subscription, so credit usage cannot pick one.	End all but one subscription.
`409` `idempotency_key_reused`	The `Idempotency-Key` was used before with a different request.	Retry the identical request with the same key, including the same `timestamp`. Use a new key for a new operation. See usage tracking.
`422` `feature_not_consumable`	The Feature is boolean or config, so there is no usage to consume.	Use a metered Feature.
`422` `credit_usage_configuration_invalid` (`no effective credit rate`)	The event time is before the credit rate became effective.	Use a later time, or fix the rate.
`400` `invalid_request`	A field is missing or malformed, for example a `timestamp` that is a date only.	Read the message and fix the field.
`400` `invalid_return_url`	The checkout `return_url` origin is not on the Engine’s allowlist.	Core also answers `422` `return_url: invalid_or_untrusted` for an origin that is neither the deployment’s nor registered in your organization’s `checkout_return_origins`. See return URLs and create checkout.
`422` `payment_provider_required`	The customer’s payment provider is not connected.	Connect it, or assign one to the customer. See checkout.
`503` `credit_usage_contention` (`Retry-After: 1`), `credit_usage_temporarily_unavailable` (`Retry-After: 1`), `credit_usage_publication_backlog` (`Retry-After: 30`)	The credit balance is busy, or publication is delayed: 1,000 or more usage events are still being retried, or the oldest is older than 5 minutes. A dead-lettered event no longer blocks usage.	Retry the same request with the same `Idempotency-Key` after the `Retry-After` seconds.
`503` `usage_unavailable` from `can()`	The usage lookup failed. The body carries a `request_id`.	Treat it as an unavailable decision, not a denial, and retry after a second. Quote the `request_id` if it persists.

An event that was accepted but never counted usually means the event name does not equal the feature code, or processing has not finished: events are processed asynchronously, so read usage again after a few seconds.