Error codes

Every endpoint of the Management API and the Public API, and the calls the Server SDK makes, answer an error with the same body. Branch on code, never on message.

The error body

json

{
  "error": {
    "code": "ACTIVE_SUBSCRIPTION_EXISTS",
    "message": "An active subscription already exists for this organization",
    "request_id": "req_...",
    "details": { "subscription_id": "sub_...", "status": "ACTIVE" }
  }
}

Field	Meaning
`code`	A stable code: one of the codes below, or a generic code named after the HTTP status
`message`	A readable English sentence for logs; it may change
`request_id`	The ID of the request; quote it when you contact us
`details`	Optional. An object with the facts named in the code's row, or, for `VALIDATION_ERROR` from request validation, a list of the rules that failed

Some answers carry headers as well: VERIFICATION_RATE_LIMITED comes with Retry-After. Unknown fields in a request body are dropped, not refused.

A failed request validation looks like this:

json

{ "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "request_id": "req_...", "details": ["email must be an email"] } }

Generic codes

An error without a code of its own carries the name of its HTTP status:

Code	HTTP status	Meaning
`BAD_REQUEST`	400	The request cannot be served as sent; the message says why
`UNAUTHORIZED`	401	No credential, or a credential that is invalid or expired
`FORBIDDEN`	403	The credential is valid but not allowed to do this
`NOT_FOUND`	404	No such resource, or not one the credential can see
`CONFLICT`	409	The resource is in a state that does not allow this
`PAYLOAD_TOO_LARGE`	413	The request body is too large
`UNSUPPORTED_MEDIA_TYPE`	415	The request body is not in a supported format
`TOO_MANY_REQUESTS`	429	Too many requests; wait and retry
`INTERNAL_SERVER_ERROR`	500	An unexpected error; retry, and contact us with the `request_id` if it persists

Any other status without a name of its own carries HTTP_ERROR.

Error codes

Each code is returned with one HTTP status. Codes are meant to stay stable, and new codes may be added; ShipRev is in beta, and until its first release a code may still be renamed or change meaning. "Returned by" names the API: Management, Public, Server SDK (the calls the Server SDK makes to your region), Hosted sign-in, or Stripe webhooks (answers to Stripe, not to you).

Validation and sessions

Code	HTTP status	Returned by	Meaning	What to do
`VALIDATION_ERROR`	400	Management, Public, Server SDK, Hosted sign-in	The request body or a parameter failed validation; details lists each failed rule when it comes from request validation.	Fix the request against the endpoint schema and resend; do not retry unchanged.
`PROJECT_CONTEXT_REQUIRED`	400	Management, Public	The session has no current application selected, and this endpoint acts on one application.	Select or switch to an application in the session, then retry.
`STATE_STORE_UNAVAILABLE`	503	Public	The short-lived state store behind social sign-in or email verification cannot be reached; nothing was changed.	Retry after a short delay with backoff.
`UPSTREAM_LEVEL_RESTRICTED`	403	Management, Public, Server SDK	ShipRev has not confirmed your plan within the validity period, so new writes are refused; details carry level, source and expired.	Reads, sign-in and usage reporting keep working; the restriction lifts on ShipRev's next answer. Contact us if it persists.
`UPSTREAM_SCOPE_VIOLATION`	403	Server SDK	The credential is scoped to one organization and the request names another.	Send requests only for the organization the credential was issued to.
`SDK_GATE_UNRESOLVED`	409	Management, Server SDK	No single end-user gate serves the application of this SDK key, so a service token cannot be issued.	Contact us with the application ID.

Code	HTTP status	Returned by	Meaning	What to do
`ACCOUNT_LINKING_VERIFICATION_REQUIRED`	409	Public	A social sign-in matched an existing account whose email is not yet verified, so the social identity cannot be linked.	Sign in with the account password (and verify the email) first, then link the social provider.
`PASSWORD_RESET_TOKEN_INVALID`	400	Public	The password reset link is invalid, expired or already used.	Request a new password reset email and use the new link.
`CURRENT_PASSWORD_INVALID`	400	Public	The current password supplied for a password change is incorrect.	Ask the user to re-enter the current password.
`EMAIL_VERIFICATION_REQUIRED`	403	Public	The account must verify its email before it can hold a session; details carry a verification ticket (email, verification_ticket, ticket_expires_in, code_sent) when returned by sign-up or sign-in.	Send the user through email verification with the returned ticket, then sign in again.
`VERIFICATION_TICKET_INVALID`	401	Public	The email verification ticket is invalid, expired or no longer matches the account.	Sign in again to obtain a fresh verification ticket.
`VERIFICATION_CODE_INVALID`	400	Public	The email verification code is incorrect.	Ask the user to re-enter the code; request a new one if needed.
`VERIFICATION_CODE_EXPIRED`	400	Public	The email verification code has expired.	Request a new verification code.
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	400	Public	Too many incorrect codes were entered for this verification code.	Request a new verification code.
`VERIFICATION_RATE_LIMITED`	429	Public	Too many verification codes were requested; the response has a Retry-After header and details.retry_after in seconds.	Wait the indicated number of seconds before requesting another code.
`EMAIL_ALREADY_VERIFIED`	409	Public	The email is already verified, so there is nothing to confirm or resend.	Treat verification as done and continue to sign-in.
`EMAIL_CHANGE_NOT_ALLOWED`	403	Public	The email of an account that joined through an invitation cannot be changed.	Keep the invited email; contact the organization admin if a different email is needed.
`S3_STORAGE_DISABLED`	501	Public	File storage is not configured in this region, so uploads such as avatars are unavailable.	Do not offer the upload.
`S3_STORAGE_UNAVAILABLE`	503	Public	The file storage bucket could not be reached.	Retry later with backoff.

Code	HTTP status	Returned by	Meaning	What to do
`OIDC_ISSUER_INVALID`	400	Management	The OIDC issuer host is not a verified brand domain of this end-user gate.	Verify the domain on the gate first, or pass a host that is already verified.
`RELYING_PARTY_GATE_INVALID`	409	Management	The gate cannot hold relying parties: it is not an end-user gate or its OIDC provider is turned off.	Use an end-user gate and turn its OIDC provider on first.
`RELYING_PARTY_NOT_FOUND`	404	Management	No relying party with this client ID exists on the gate.	Check the client ID and gate, or list the gate's relying parties.
`RELYING_PARTY_PUBLIC_CLIENT`	409	Management	A public client has no secret, so its secret cannot be rotated.	Rotate secrets only for confidential clients.
`OIDC_INTERACTION_INVALID`	400	Hosted sign-in	The sign-in interaction is unknown, expired, already answered or not bound to this browser.	Restart the authorization from the relying party.
`OIDC_LOGIN_REJECTED`	401	Hosted sign-in	The token presented to complete the sign-in is not a valid session token of this gate.	Sign the user in again on this gate and submit the new session token.
`OIDC_ACCOUNT_UNAVAILABLE`	403	Hosted sign-in	The account cannot sign in: it is disabled, unverified or has no membership.	Resolve the account state (verify email, restore access) before retrying; do not loop.
`OIDC_STORE_UNAVAILABLE`	503	Hosted sign-in	The OIDC interaction store is temporarily unavailable.	Retry after a short delay, restarting the authorization if the interaction expired.
`GATE_AMBIGUOUS`	409	Management	The application is served by more than one end-user gate, so the target gate is ambiguous.	Contact us; the application's gate setup must be resolved.
`GATE_RETURN_URL_REQUIRED`	400	Management	default_return_url is required while the customer portal is off.	Set default_return_url, or keep the portal on.

Products and plans

Code	HTTP status	Returned by	Meaning	What to do
`VERSION_IMMUTABLE`	400	Management	A published plan version cannot be modified.	Create a new plan version and edit that draft instead.
`VERSION_ALREADY_PUBLISHED`	400	Management	The plan version has already been published.	Treat it as published; create a new version for further changes.
`PLAN_ALREADY_ARCHIVED`	400	Management	The plan is already archived.	No action needed; treat the archive as done.
`PLAN_PRICE_NOT_ZERO`	400	Management	A plan subscribed without a payment method can only have versions priced 0.	Set the price to 0 or turn off the no-card option for the plan.
`EXTERNAL_SYNC_FAILED`	502	Management	Synchronizing the plan price with the payment provider failed.	Retry the publish or connection step later; check the payment connection if it persists.

Subscriptions and checkout

Code	HTTP status	Returned by	Meaning	What to do
`INSUFFICIENT_ROLE`	403	Public	Only an owner or admin of the organization can change its billing.	Ask an owner or admin of the organization to perform the action.
`ACTIVE_SUBSCRIPTION_EXISTS`	409	Management, Public	The organization already holds an active or past-due subscription; details carry subscription_id and status.	Change the plan of the existing subscription instead of creating a new one.
`CHECKOUT_PENDING_CONFIRMATION`	409	Public	A previous checkout for the organization was paid and is awaiting confirmation; details name the pending subscription.	Wait for confirmation and read the subscription again instead of starting a new checkout.
`CHECKOUT_IN_PROGRESS`	409	Management, Public	Another checkout for the organization is in progress; details name the pending subscription.	Complete or let the open checkout expire, then retry.
`PLAN_VERSION_NOT_FOUND`	404	Management, Public	The plan version does not exist in this application.	Check the plan_version_id against the published catalog.
`PLAN_NOT_PUBLISHED`	400	Management, Public	The plan version is not published, or has no payment provider price yet.	Publish the plan version (with a payment connection in place) before subscribing to it.
`PLAN_NOT_NO_CARD`	400	Public	This plan version cannot be subscribed without a payment method.	Use checkout with a payment method for this plan.
`PLAN_ACCOUNT_LIMIT_REACHED`	409	Public, Stripe webhooks	The account already holds a subscription to this plan in another organization; details may carry organization_id.	Use the existing subscription, or choose another plan.
`SUBSCRIPTION_NOT_FOUND`	404	Management, Public	No matching subscription was found (or no active one to change or cancel).	Check the subscription ID or the organization's current subscription.
`SUBSCRIPTION_NOT_ACTIVE`	409	Management, Public	The subscription is not active (past due, canceled, or canceled at the payment provider); details carry subscription_id and status.	Read the subscription status; settle or create a subscription as appropriate.
`SUBSCRIPTION_PROVIDER_MANAGED`	409	Management	The subscription is managed by the payment provider and cannot be ended here; details carry subscription_id and origin.	Cancel it through the payment provider flow instead.
`PLAN_UNCHANGED`	409	Management, Public	The subscription is already on the requested plan version.	No action needed.
`PLAN_CHANGE_NOT_ALLOWED`	400	Management, Public	This plan change is not supported (for example a different product or currency, an add-on plan, or the provider refused it).	Choose a compatible target plan version, or cancel and subscribe anew.
`PLAN_CHANGE_CONFLICT`	409	Management, Public	The subscription changed while the plan change was being made.	Read the subscription again and retry the change.
`NO_ACTIVE_SUBSCRIPTION`	None	None	Reserved: the organization has no active subscription. No endpoint returns it today.	No action needed.
`INVALID_RETURN_URL`	400	Public	return_url must be an https address on a verified brand domain of the gate.	Pass a return_url on a verified brand domain.
`BUYER_CUSTOMER_NOT_FOUND`	409	Public	The organization has no payment provider customer yet, so there is no billing portal or invoice history.	Complete a paid checkout first.
`CUSTOMER_EXISTS`	409	Management	A customer with this email already exists; details carry account_id.	Use the existing customer.

Payment connection and webhooks

Code	HTTP status	Returned by	Meaning	What to do
`PAYMENT_PROVIDER_UNAVAILABLE`	503	Management, Public, Stripe webhooks	The payment provider could not be reached or did not complete the call.	Retry later with backoff.
`PAYMENT_PROVIDER_NOT_CONFIGURED`	503	Management, Public	The application has no active payment connection.	Configure a payment connection for the application, then retry.
`PAYMENT_CONNECTION_NOT_FOUND`	404	Management	The application has no payment connection.	Configure a payment connection first.
`PAYMENT_CONNECTION_UNAVAILABLE`	410	Stripe webhooks	The payment connection addressed by the webhook does not exist or is disabled.	Payment provider side: remove or update the webhook endpoint.
`PAYMENT_CONNECT_NOT_CONFIGURED`	409	Management	Connect with Stripe is not available in this region.	Connect with your own Stripe keys instead.
`PAYMENT_CONNECT_HOST_UNSUPPORTED`	409	Management	Stripe Connect authorization can only be started on the configured console host.	Open the payment settings on the host named in the message and start again.
`PAYMENT_CONNECT_REVOKED`	409	Management	The Stripe account was disconnected while the authorization was completing.	Start the Stripe Connect authorization again.
`PAYMENT_CONNECT_STATE_INVALID`	400	Management	The Stripe Connect authorization state is invalid, expired or already used.	Start the Stripe Connect authorization again.
`PAYMENT_CONNECT_MODE_MISMATCH`	400	Management	The Stripe account was connected in a different mode, live or test, than the region runs Connect with Stripe in.	Connect the account again in the mode the page names.
`PAYMENT_CONNECT_EXCHANGE_FAILED`	502	Management	Stripe did not accept the authorization code.	Start the Stripe Connect authorization again.
`PAYMENT_CONNECT_REVOKE_FAILED`	502	Management	Payment collection was stopped, but Stripe did not confirm the disconnection.	Call disconnect again to retry.
`WEBHOOK_CONFIG_UNREADABLE`	400	Stripe webhooks	The payment connection configuration could not be read to verify the webhook.	Payment provider side: redelivery will fail until the connection is reconfigured; contact us if it persists.
`WEBHOOK_SIGNATURE_INVALID`	400	Stripe webhooks	The webhook signature is missing or invalid.	Payment provider side: check the webhook signing secret.
`RECHARGE_RECEIPT_SCOPE_MISMATCH`	422	Stripe webhooks	A payment receipt delivered by the payment provider names an organization or application outside this payment connection.	Payment provider side: nothing is recorded; contact us if it persists.

Usage and wallets

Code	HTTP status	Returned by	Meaning	What to do
`OCCUPANCY_LIMIT_REACHED`	409	Public	The allowance of this entitlement is fully occupied.	Release an existing occupancy or upgrade the plan, then retry.
`OCCUPANCY_NOT_RESERVED`	409	Public	The occupancy is no longer reserved (it expired or was released).	Reserve a new occupancy and confirm it before it expires.
`INSUFFICIENT_CREDITS`	400	Management	The wallet adjustment would leave a negative balance.	Use a smaller debit.
`INSUFFICIENT_BALANCE`	None	None	Reserved. No endpoint returns it today.	No action needed.

Export, import and provisioning

Code	HTTP status	Returned by	Meaning	What to do
`PROJECT_NOT_FOUND`	404	Management	The application does not exist or is not accessible to the caller.	Check the application ID.
`BUNDLE_INVALID`	400	Management	The import bundle is malformed, or a writing import lacks confirm equal to the application ID.	Fix the bundle, or pass confirm (or use dry_run=true to check only).
`BUNDLE_TOO_LARGE`	413	Management	The import bundle exceeds the size limit.	Reduce the bundle size below the limit stated in the message.
`BUNDLE_INCONSISTENT`	422	Management	The bundle is internally inconsistent or does not match the written state; nothing was written.	Export a fresh bundle and import it again.
`IMPORT_IN_PROGRESS`	409	Management	An import into this application is already running.	Wait for the running import to finish, then retry.
`GATE_SHAPE_UNSUPPORTED`	409	Management	Export and import support only applications with their own end-user gate.	Contact us.
`ID_CONFLICT`	409	Management	An identifier or unique value in the bundle is already used outside this application.	Import into the application the bundle came from, or remove the conflicting record.
`IDEMPOTENCY_KEY_REUSED`	409	Management	The Idempotency-Key was already used with a different provisioning request.	Use a new Idempotency-Key for a different request, or resend the original request unchanged.
`PROVISIONING_CANCELLED`	409	Management	The provisioning request bound to this Idempotency-Key was cancelled.	Start again with a new Idempotency-Key.
`TENANT_SLUG_TAKEN`	409	Management	The requested tenant slug is already in use.	Choose a different slug.

Errors in the Server SDK

The Server SDK turns HTTP answers into errors as follows; the Server SDK reference lists every error it throws.

HTTP answer	What you see
`401` on any call	The client renews its service token once and sends the call again; only a second `401` reaches you
Another error from `reserve()`, `confirm()` or `release()`	An `Error` with a numeric `status` and the error body in its message. A reservation the allowance cannot cover is a `400`, a capability the plan does not grant a `404`, a reservation already confirmed or released a `409`
An error while sending buffered usage	Nothing is thrown: the events go to the backlog and to `on_flush_failure`, and are sent again
A usage event the region refuses	Nothing is thrown: the event goes to `on_rejected` with its reason, and is not sent again
A timeout	An `Error` naming the timeout, set by `presets.connect_timeout_ms`

Session tokens are verified locally, so verifyToken() makes no request: its failures are TokenRejectedError or Error, and your service answers them with a 401. The capability guard answers a refusal with a 403.

The error body

Generic codes

Error codes

Validation and sessions

Sign-in, accounts and email verification

Hosted sign-in and OIDC

Products and plans

Subscriptions and checkout

Payment connection and webhooks

Usage and wallets

Export, import and provisioning

Errors in the Server SDK