Errors

Every error the Railbed API returns, with its HTTP status, what caused it and what to do next.

On this page

The error object

Every error has an HTTP status of 400 or above and the same JSON body:

An error
{
  "error": {
    "code": "no_payout_wallet",
    "message": "Add a payout wallet in Settings → Payout wallet before taking Live payments, or use a Test key (rb_test_…) to try the API without one."
  }
}
409 Conflict
FieldTypeDescription
codestringStable and machine-readable. Branch on this
messagestringA sentence for people. It can be reworded at any time, so show it or log it, but never parse it
fieldstringThe request field at fault, when there is one: amount, metadata, order.items[0].amount, starting_after
reason, providersstring, arrayOnly with no_providers on a session start: why no card provider is offered, and the provider ids it is about. See Why no provider is offered

Handling errors

Decide by status first, then by code where it matters:

StatusMeaningWhat your code should do
400The request was invalidFix the request. Retrying it unchanged fails the same way
401The key or agent access token is missing, malformed, expired or revokedFor a secret key, check the key and its mode, and don't retry. An agent gets a new access token on invalid_token, and asks its person to connect it again on agent_disconnected
403Not allowed for this account, key or agentDon't retry. On insufficient_scope, use a key or agent with Full access
404Not found in this account and modeCheck the id. When the object is yours but in the other mode, the message says so: use a key of that mode
405This path uses a different HTTP methodUse a method named in the Allow header
409The object's state doesn't allow thisRead the object and act on its current status. The one retryable 409 is idempotency_in_progress: wait for Retry-After seconds and send the same create again
410The session can't be paid any moreCreate a new session
413, 415The body is too large or isn't JSONFix the request
429Rate limitedWait for Retry-After seconds, then retry
500, 502, 503Something failed on our side or upstreamRetry with backoff. Checkout-session creates are safe to retry with the same Idempotency-Key; other endpoints have their own retry rules
A small error handler
async function railbed(path, init = {}) {
  const res = await fetch(`https://pay.railbed.io/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  });
  const body = await res.json();
  if (res.ok) return body;
  const err = Object.assign(new Error(body.error.message), {
    status: res.status,
    code: body.error.code,
    field: body.error.field,
  });
  err.retryable = res.status === 429 || res.status >= 500 || err.code === 'idempotency_in_progress';
  err.retryAfter = Number(res.headers.get('Retry-After')) || null;
  throw err;
}

Every code

400 Bad Request

CodeEndpointCause
invalid_jsonAny with a bodyThe body isn't a JSON object
invalid_amountCreateamount isn't a string, isn't from "1.00" to "100000.00" with at most two decimal places, or is under the smallest card payment (about "2.00" USD; the message names it). See Provider minimums
invalid_currencyCreatecurrency isn't USD, EUR, GBP, CAD, AUD, INR or SEK
missing_descriptionCreatedescription is missing, blank or not a string
too_longCreatedescription or reference is over 120 Unicode code points after normalization. Exactly 120 is allowed. See field
invalid_referenceCreatereference isn't a string
invalid_emailCreate, Startcustomer_email or customer.email isn't a valid address, or Start needs one and none is on the session
invalid_urlCreatesuccess_url or cancel_url isn't a full http(s):// address, has a username or password, is over 1,000 characters, is a Railbed page, or in Live mode isn't a public https:// address (localhost and private network addresses are refused). The message says which
invalid_metadataCreateOver 20 keys; a blank, duplicate, over-40-code-point or __-prefixed key after normalization; or a value that is not a string of at most 500 code points
invalid_idempotency_keyCreate a session or invoiceThe Idempotency-Key header is blank, over 120 characters or has characters other than printable ASCII
invalid_customerCreatecustomer isn't an object, or customer.email and customer_email are different addresses
invalid_orderCreateA field in order has the wrong type, is too long or is out of range, such as a quantity that isn't a whole number from 1 to 100,000 or an item without name or amount. See field
field_not_allowedCreate from a checkoutamount, currency, description, collect or order was sent with checkout, which decides them. See field and From a saved checkout
invalid_checkoutCreate from a checkoutcheckout isn't the id or slug of one of your checkouts in this key's mode
invalid_planCreate from a checkoutplan is missing for a pricing table or isn't one of its plans, option is missing for a table with a switch or isn't 0 or 1, or either was sent for a page or widget. See field
invalid_order_totalsCreateThe items less discount plus shipping and tax don't equal amount to the cent, or without items, shipping and tax less discount come to more than amount
invalid_countryStartcountry isn't a two-letter code such as US
invalid_limitAny listlimit isn't a whole number from 1 to 100
invalid_cursorAny liststarting_after isn't one of your payments, payment links, invoices, checkouts, orders, customers or webhook endpoints (whichever you're listing) in this mode
invalid_statusList paymentsstatus isn't open, pending, paid, held, failed or expired
invalid_status, invalid_fulfillmentList ordersstatus isn't an order status (open, pending, paid, held, failed, expired or canceled), or fulfillment isn't none, unfulfilled or fulfilled
invalid_referenceList paymentsreference is over 120 characters
invalid_created_gte, invalid_created_lteList payments, payment links, invoices or ordersThe value isn't a Unix timestamp in seconds
invalid_due_date_gte, invalid_due_date_lteList invoicesThe value isn't a YYYY-MM-DD date
invalid_datesList payments, payment links, invoices or orderscreated_gte is later than created_lte, or (invoices) due_date_gte is later than due_date_lte
invalid_event_typeReport a cancellation or refundtype isn't canceled or refunded
invalid_event_idReport a cancellation or refundid is missing, over 64 characters or has spaces
invalid_amountReport a cancellation or refundamount isn't a decimal string from "0.01" to the order's total, or was sent with canceled
invalid_outcomeSimulateoutcome isn't paid, underpaid, declined or failed
invalid_fulfillmentUpdate an orderfulfillment is missing or isn't none, unfulfilled or fulfilled
invalid_urlCreate a webhook endpointurl isn't a full https:// address, has a username or password, is over 2,048 characters, or in Live isn't on the public internet
invalid_eventsCreate or update a webhook endpointevents is empty, isn't a list, or names a type that doesn't exist
invalid_descriptionCreate or update a webhook endpointdescription isn't text
too_longCreate or update a webhook endpointdescription is over 80 characters
not_editableUpdate a webhook endpointurl was sent: an endpoint's address can't be changed. Delete the endpoint and create one at the new address
invalid_description, too_longCreate a payment linkdescription isn't a string, or a text field is over its limit. See field
invalid_customer_name, invalid_customer_phone, invalid_reference, invalid_memoCreate a payment linkThat field isn't a string
invalid_addressCreate a payment linkshipping_address or billing_address lacks a line, city, region or postal code its country needs. See field
invalid_expiryCreate a payment linkexpires_in_days isn't a whole number from 1 to 365 (a JSON number, not a string)
invalid_payout_walletCreate a payment linkpayout_wallet_id isn't one of the account's saved wallets, or it was removed. List payout wallets gives each saved wallet's id, and Settings → Payout wallet → Other wallets shows it with Copy ID
invalid_collectCreate a session, payment link or checkoutcollect asks for something it can't. See field
invalid_kindCreate a checkout, List checkoutskind isn't page (create) or a kind of checkout (list)
missing_name, too_longCreate a checkoutname is empty, or a text field is over its limit. See field
invalid_description, invalid_button_labelCreate a checkoutThat field isn't a string
invalid_theme, invalid_valueCreate a checkouttheme isn't light or dark, or crypto isn't a boolean
invalid_routingCreate a checkout or payment linkrouting names no choice, or a provider that can't take card payments; on a payment link, also an empty providers list or a provider you turned off. See field
invalid_invoice_idList paymentsinvoice_id isn't an invoice id (in_…)
unknown_fieldCreate, update, send or void an invoiceThe body has a field invoices don't have. The message names the nearest one (unitAmount → unit_amount), and field names the one sent
invalid_customerCreate or update an invoice, List invoicescustomer isn't an object, customer.id isn't one of your customers in this mode, or a customer field isn't text; on the list, customer isn't a customer id
invalid_linesCreate or update an invoicelines is empty, has more than 50 lines, or a line isn't an object or its description isn't text. See field
missing_descriptionCreate or update an invoiceA line has no description. See field
invalid_quantityCreate or update an invoiceA line's quantity isn't from 0.01 to 99,999 with up to two decimals
invalid_amountCreate or update an invoiceA line's unit_amount, discount.amount or min_payment isn't a decimal string, or the total is under 1.00 or over 100,000.00, or under the smallest card payment the invoice's providers take
invalid_discount, invalid_taxCreate or update an invoiceThe discount isn't an amount or a percentage from 0.01 to 100, or is both, or the tax isn't a percentage from 0 to 100 (or its label isn't text)
invalid_memo, invalid_terms, invalid_reference, too_longCreate or update an invoiceThat field isn't text, or a text field is over its limit. See field
invalid_due_dateCreate or update an invoicedue_date isn't a YYYY-MM-DD date from today to two years ahead
invalid_valueCreate or update an invoiceallow_partial, allow_tip or email_receipts isn't true or false
invalid_min_paymentCreate or update an invoicemin_payment is under 1.00 or isn't less than the total
invalid_remindersCreate or update an invoicereminders isn't a list of days from -7, -3, -1, 0, 1, 3, 7, 14 and 30
invalid_ownerCreate or update an invoice, List invoicesowner_id or owner_email isn't an owner, manager or salesperson of the business, or both were sent; on the list, owner isn't a user id or none
invalid_issue, invalid_send, invalid_messageCreate or send an invoiceissue or send isn't true or false, or message isn't text, is over 1,000 characters, or was sent without send
invalid_expected_versionUpdate an invoiceexpected_version isn't a whole number
not_editableUpdate an invoicepayout_wallet_id was sent for an invoice already issued: the wallet is chosen before it's sent
customer_requiredCreate or send an invoiceEmailing an invoice (send) needs the customer's name and email; sharing its url needs neither. See field
invalid_status, invalid_kindList invoicesstatus isn't an invoice status or unpaid, or kind isn't invoice or link
invalid_reasonVoid an invoicereason isn't text

401 Unauthorized

Every 401 carries a WWW-Authenticate header that points to the API's protected resource metadata, where an agent can find out how to get access.

CodeCause
invalid_api_keyNo Authorization: Bearer header, a malformed key, or a revoked one (the message says so). Create a key in Developers, which also shows a revoked key that something still sends
invalid_tokenAn agent's access token expired, is malformed, or wasn't issued for Railbed. Get a new one from the token endpoint described in auth.md
agent_disconnectedThe agent was disconnected in the dashboard, or the person who connected it no longer manages keys for the business. Ask an owner or developer to connect it again

403 Forbidden

CodeCause
merchant_read_onlyThe account is suspended or archived: reads and lists still work, and webhook endpoints can still be deleted, but nothing can be created or changed. Email support@railbed.com
integration_disabledThe integration this key belongs to (the API, or WooCommerce for a WooCommerce key) is turned off for this account, so sessions can't be created or started; or payment links or checkouts are turned off, so they can't be created (nor sessions from a checkout made or started). Email support@railbed.com
insufficient_scopeThe key's or agent's access level doesn't include the scope this endpoint needs, such as a Read only key creating a checkout session. The message and the WWW-Authenticate header (error="insufficient_scope", scope="…") name the scope. Use a key or agent with Full access
live_paymentSimulate was called on a Live payment. Only Test payments can be simulated

404 Not Found

CodeCause
not_foundNo such session, payment, payment link, invoice, checkout, order, customer or webhook endpoint in your account in this key's mode (a removed webhook endpoint included), or no such API endpoint. A Test key can't see Live objects and the other way round: for a session, payment, payment link or invoice of yours in the other mode, the message names its mode, such as pay_… is a Live payment, and this is a Test key. Use a Live key for it.

405 Method Not Allowed

CodeCause
method_not_allowedThe path exists but does not support this HTTP method. The Allow header lists supported methods. Authentication and access errors still take precedence

409 Conflict

CodeEndpointCause
idempotency_conflictCreate a session or invoiceThe key was used with a different validated, normalized body. Don't retry: use a new key for a different request
idempotency_in_progressCreate a session or invoiceAnother request with this key hasn't finished yet. Retry the same request with the same key after the Retry-After seconds (1)
no_payout_walletCreate a session, payment link, checkout or invoice, issue or send an invoiceLive mode needs a payout wallet that can take live payments: none is saved, or the saved one can't (the message says why). Add or change it in Settings, or build with a Test key meanwhile: Test mode needs no wallet
account_reviewCreate a session, payment link, checkout or invoice, issue or send an invoiceLive payments are paused for the account for now. Nothing was created. Build with a Test key meanwhile: Test mode works as usual, and payments already started still complete. The account's owner can ask support when Live will be back
payout_wallet_unusableCreate a payment link or invoiceLive mode, and the saved wallet in payout_wallet_id can't take live payments (the message says why). Choose another wallet, or ask an owner to replace it in Settings
order_paidCreateThe store order in order.id is already paid, or held with money you could accept as paid or that part-paid it. Nothing was created. Check the order before asking the buyer to pay again. See Store orders and retries
order_erasedCreateThe store order in order.id belongs to a customer whose details you deleted. Use a new order.id for a new order
checkout_offCreate from a checkoutThe checkout is turned off, so it takes no new sessions. Turn it on in the dashboard first
checkout_deletedCreate from a checkoutThe checkout was deleted. Use another checkout
commerce_pausedCreate, StartThe account has paused taking payments. Nothing was created or started. Applies to payment links, checkouts and invoices too
unavailableStartThe account can't take Live payments now: its payout wallet is missing or can't take payments, Live payments are paused for the account, or the card network refused the account's setup. Nothing was started or charged. Retrying gives the same answer: fix the payout wallet in Settings, or email support if the message says the network refused it
no_providersStartNo card provider can take this payment. reason says why (providers_off, below_minimum, country, unavailable or closing) and providers names the ones it is about: see Why no provider is offered. Nothing was started
already_paidStartThe payment is complete
heldStartThe money already arrived but didn't pass a check; the dashboard shows the payment as Needs your decision
failedStartThe payment was declined. Create a new session
start_changedStartThe account's payment settings changed while the session was starting. Nothing was started; try again
not_startedSimulateNobody has started the session yet. Start it with POST /v1/checkout_sessions/:id/start (send customer_email if the session has none), then simulate
not_cancelableCancel a session or payment linkThe buyer has gone to a card provider or been shown a crypto address, the payment is paid, held, failed or expired, or it's a buyer's own attempt on a checkout page or a Shopify checkout. The message says which. Nothing changed
event_conflictReport a cancellation or refundThat id was already recorded with a different type or amount. Send a new id for a new event
duplicate_urlCreate a webhook endpointThat address is already one of your endpoints in this mode. Delete that endpoint, then create it again
too_manyCreate a webhook endpointThis mode already has 10 endpoints. Remove one first
payment_linkChange, send, void or delete an invoiceIt's a payment link's invoice (kind: "link"): change or cancel it through Payment links
invoice_changedUpdate an invoiceSomeone changed the invoice since the version you sent in expected_version. Read it again, then make your change
invoice_changed, already_paidStart, for a payment toward an invoiceLess is due on the invoice now than the payment asks for, or the invoice is paid in full. Nothing was started. The customer pays what's left from the invoice's page
invoice_not_editableUpdate an invoiceA payment toward it has started, so only the due date, reminders, memo, terms, receipts and owner can change; or it's paid or void, so only its owner can. The message says why; field names the first field refused
already_issuedIssue an invoiceIt's already issued
invoice_not_payableSend an invoiceIt's paid, void or expired, so there's nothing to send
email_blockedSend an invoiceEmail can't be sent for this business right now (the message says why, such as a paused business). Share the invoice's url instead
email_suppressedSend an invoiceThe customer's address bounced or marked an earlier email as spam, so Railbed won't email it again. Fix the address, or share the url another way
already_paid, invoice_draftVoid an invoiceIt's paid, or it's a draft (delete a draft instead)
not_draftDelete a draft invoiceIt's issued. Void it instead, so its number and history stay

410 Gone

CodeCause
expiredThe session passed its expires_at without being paid
canceledThe session or payment link was canceled
invoice_voidStart, for a payment toward an invoice that was voided. Nothing was started

Size, type and rate

StatusCodeCause
413request_too_largeThe body is over 64 KiB
415unsupported_media_typeThe body isn't sent as Content-Type: application/json
429rate_limitedOver about 120 requests a minute (each connected agent has its own 120, and a business's agents share 600), 12 starts a minute, or about 60 requests a minute from one address with a missing or invalid key. Every 429 includes Retry-After (currently 60 seconds for these limits); wait that long
429email_too_soonSend an invoice: it was emailed less than a minute ago. Wait a minute
429email_limitSend an invoice: it was emailed 10 times today, or the business sent 200 invoice emails today. Share the invoice's url, or send it tomorrow

5xx

StatusCodeCause
500internalSomething failed on our side. Retry with backoff; email support@railbed.com if it continues
502network_unavailableThe card network didn't answer while starting. Retry in a minute
503misconfiguredCard payments are briefly unavailable. Retry later
503payments_pausedStart, Live only: new payments are paused for a few minutes while a problem is fixed. Nothing was started; retry shortly. Sessions already started still complete
503auth_unavailableAn agent's access token couldn't be checked because the sign-in service didn't answer. Retry in a minute with the same token
503email_unavailableSend an invoice: email can't be sent right now. Share the invoice's url with the customer yourself

Updated · This page as Markdown