HTTP API

ORBCART DOCUMENTATION

Errors

Every error code, what caused it and what to do next.

A failed request answers with a Problem. The SDKs throw it as CommerceError:

try {
  await cart.add("BACKPACK-30-GREEN");
} catch (error) {
  if (error instanceof CommerceError) {
    error.problem.code; // what happened
    error.problem.kind; // the category
    error.problem.retryable; // may the same request succeed later?
    error.problem.cart; // the Cart as it is, when the buyer can fix it
  }
}

Not errors: a declined payment, quote_changed and pending are normal results of pay() and accept(). Outcomes →

Decide by kind

When you meet a code you don't handle, kind tells you the general next step:

kindNext step
invalidFix the input. Show the buyer what to correct.
unauthorizedThe credential is missing or wrong. A bug in your setup.
forbiddenThe credential is valid but not allowed here.
not_foundThe Cart, Quote or Order doesn't exist for this credential.
conflictThe state moved on. Read the Cart again and continue from there.
rate_limitedWait and repeat with the same Idempotency-Key.
unavailableA system is temporarily away. Repeat later with the same key.
internalOur bug. Report the requestId.

The buyer can fix it

Show a friendly message. describe(locale).problem(code) has one in four languages.

CodeCauseWhat to do
cart_incompleteDetails missing for a Quote.Ask for problem.missing.
ship_to_invalidThe address fails the country's rules.Highlight problem.invalid, such as postalCode.
bill_to_invalidSame, for the billing address.Highlight problem.invalid.
ship_to_incompleteA partial address where a full one is needed.Ask for the full address.
ship_to_unsupportedYou don't ship to this country.Let the buyer choose another country.
shipping_method_unavailableThe chosen method isn't offered here.Show cart.shippingMethods again.
not_shippableSome Lines can't go to this address.Offer to remove problem.lines.
lines_unavailableLines can no longer be bought.Offer to remove problem.lines.
code_invalidThe code applies to nothing in this Cart.Say so at the code field.
quantity_invalidNot a positive whole number.Correct the quantity field.
configuration_invalidA line extension value was refused.Map problem.errors[].pointer to your fields.
extension_invalidA Cart extension value was refused.Map errors, or fix the names in invalid.
payment_method_unavailableThe method doesn't fit this buyer.Offer quote.paymentMethods.
tax_undeterminableNo tax for problem.country and taxCategory.Your tax setup. Let the buyer pick another address.

The purchase moved on

CodeCauseWhat to do
cart_lockedA payment for this Cart is running.Reopen its Quote with openQuote() or resume(). Don't start another.
cart_orderedThe Cart already became an Order.commerce.continueShopping(token).
cart_not_orderedcontinueShopping before the purchase was handed over.Keep using the current Cart.
cart_mergedThe buyer signed in and this Cart joined theirs.Continue with the Cart from identify().
quote_not_currentThe Cart changed after this Quote.Ask for a new Quote.
preparation_unavailable, preparation_unknownA PayPal approval expired or doesn't match.Start the express step again.
payment_instrument_requiredAn agent or server accepted without a token.Pass instrument to accept().

Not found

cart_not_found, line_not_found, quote_not_found, order_not_found, payment_not_found, component_not_found, event_not_found, receiver_not_found, route_not_found.

A cart_not_found on a saved token usually means the Cart expired after 180 days without activity, or it belongs to a signed-in buyer whose token is missing. Start a new Cart quietly.

Setup and credentials

Fix these in your code or configuration. Buyers should never see them.

CodeCause
credential_missingNo Authorization header.
credential_invalidUnknown key or token, or one of another environment.
environment_mismatchA test key against live, or the other way round.
not_permittedThe credential may not do this, such as a publishable key on an Admin route.
not_a_memberExplorer access without membership. members add →
origin_not_allowedThe browser's origin isn't in the Channel's origins.
buyer_token_invalidThe OrbCart-Buyer token is expired or from an unknown issuer.
buyer_token_missingidentify() without a signed-in buyer.
buyer_token_unexpectedA buyer token next to a secret key.

Request format

CodeCause
malformed_jsonThe body isn't valid JSON.
request_invalidThe body doesn't match the schema. See problem.errors.
idempotency_key_requiredThis operation needs an Idempotency-Key.
idempotency_key_invalidThe key is malformed.
idempotency_key_reusedThe same key with a different body. Use a new key.
request_in_progressThe first request with this key is still running. Repeat shortly.

Temporarily unavailable

Repeat the same request with the same key, after a short pause. Check retryable on the Problem to be sure.

temporarily_unavailable, provider_unavailable, identity_unavailable, projection_unavailable, invalidation_pending, internal_error.

Refunds and fulfillment

CodeCause
refund_exceeds_orderMore units than the Order has left.
refund_exceeds_capturedMore money than was captured.
nothing_to_refundThe selection adds up to zero.
refund_changedThe amount differs from expectedAmount. Preview again.
fulfillment_exceeds_orderMore units shipped than ordered.

Webhooks

provider_webhook_invalid, provider_webhook_signature_invalid and provider_webhook_unavailable go to the payment provider, not to you. A signature error almost always means a wrong webhook secret, or two Adyen webhooks on the same URL.

Support

Every Problem has a requestId. Log it, never the request body. It finds the request in the Explorer without exposing personal data.

On this page