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:
{
"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
| Field | Type | Description |
|---|---|---|
code | string | Stable and machine-readable. Branch on this |
message | string | A sentence for people. It can be reworded at any time, so show it or log it, but never parse it |
field | string | The request field at fault, when there is one: amount, metadata, order.items[0].amount, starting_after |
reason, providers | string, array | Only 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:
| Status | Meaning | What your code should do |
|---|---|---|
400 | The request was invalid | Fix the request. Retrying it unchanged fails the same way |
401 | The key or agent access token is missing, malformed, expired or revoked | For 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 |
403 | Not allowed for this account, key or agent | Don't retry. On insufficient_scope, use a key or agent with Full access |
404 | Not found in this account and mode | Check the id. When the object is yours but in the other mode, the message says so: use a key of that mode |
405 | This path uses a different HTTP method | Use a method named in the Allow header |
409 | The object's state doesn't allow this | Read 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 |
410 | The session can't be paid any more | Create a new session |
413, 415 | The body is too large or isn't JSON | Fix the request |
429 | Rate limited | Wait for Retry-After seconds, then retry |
500, 502, 503 | Something failed on our side or upstream | Retry with backoff. Checkout-session creates are safe to retry with the same Idempotency-Key; other endpoints have their own retry rules |
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
| Code | Endpoint | Cause |
|---|---|---|
invalid_json | Any with a body | The body isn't a JSON object |
invalid_amount | Create | amount 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_currency | Create | currency isn't USD, EUR, GBP, CAD, AUD, INR or SEK |
missing_description | Create | description is missing, blank or not a string |
too_long | Create | description or reference is over 120 Unicode code points after normalization. Exactly 120 is allowed. See field |
invalid_reference | Create | reference isn't a string |
invalid_email | Create, Start | customer_email or customer.email isn't a valid address, or Start needs one and none is on the session |
invalid_url | Create | success_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_metadata | Create | Over 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_key | Create a session or invoice | The Idempotency-Key header is blank, over 120 characters or has characters other than printable ASCII |
invalid_customer | Create | customer isn't an object, or customer.email and customer_email are different addresses |
invalid_order | Create | A 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_allowed | Create from a checkout | amount, currency, description, collect or order was sent with checkout, which decides them. See field and From a saved checkout |
invalid_checkout | Create from a checkout | checkout isn't the id or slug of one of your checkouts in this key's mode |
invalid_plan | Create from a checkout | plan 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_totals | Create | The 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_country | Start | country isn't a two-letter code such as US |
invalid_limit | Any list | limit isn't a whole number from 1 to 100 |
invalid_cursor | Any list | starting_after isn't one of your payments, payment links, invoices, checkouts, orders, customers or webhook endpoints (whichever you're listing) in this mode |
invalid_status | List payments | status isn't open, pending, paid, held, failed or expired |
invalid_status, invalid_fulfillment | List orders | status isn't an order status (open, pending, paid, held, failed, expired or canceled), or fulfillment isn't none, unfulfilled or fulfilled |
invalid_reference | List payments | reference is over 120 characters |
invalid_created_gte, invalid_created_lte | List payments, payment links, invoices or orders | The value isn't a Unix timestamp in seconds |
invalid_due_date_gte, invalid_due_date_lte | List invoices | The value isn't a YYYY-MM-DD date |
invalid_dates | List payments, payment links, invoices or orders | created_gte is later than created_lte, or (invoices) due_date_gte is later than due_date_lte |
invalid_event_type | Report a cancellation or refund | type isn't canceled or refunded |
invalid_event_id | Report a cancellation or refund | id is missing, over 64 characters or has spaces |
invalid_amount | Report a cancellation or refund | amount isn't a decimal string from "0.01" to the order's total, or was sent with canceled |
invalid_outcome | Simulate | outcome isn't paid, underpaid, declined or failed |
invalid_fulfillment | Update an order | fulfillment is missing or isn't none, unfulfilled or fulfilled |
invalid_url | Create a webhook endpoint | url 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_events | Create or update a webhook endpoint | events is empty, isn't a list, or names a type that doesn't exist |
invalid_description | Create or update a webhook endpoint | description isn't text |
too_long | Create or update a webhook endpoint | description is over 80 characters |
not_editable | Update a webhook endpoint | url was sent: an endpoint's address can't be changed. Delete the endpoint and create one at the new address |
invalid_description, too_long | Create a payment link | description isn't a string, or a text field is over its limit. See field |
invalid_customer_name, invalid_customer_phone, invalid_reference, invalid_memo | Create a payment link | That field isn't a string |
invalid_address | Create a payment link | shipping_address or billing_address lacks a line, city, region or postal code its country needs. See field |
invalid_expiry | Create a payment link | expires_in_days isn't a whole number from 1 to 365 (a JSON number, not a string) |
invalid_payout_wallet | Create a payment link | payout_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_collect | Create a session, payment link or checkout | collect asks for something it can't. See field |
invalid_kind | Create a checkout, List checkouts | kind isn't page (create) or a kind of checkout (list) |
missing_name, too_long | Create a checkout | name is empty, or a text field is over its limit. See field |
invalid_description, invalid_button_label | Create a checkout | That field isn't a string |
invalid_theme, invalid_value | Create a checkout | theme isn't light or dark, or crypto isn't a boolean |
invalid_routing | Create a checkout or payment link | routing 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_id | List payments | invoice_id isn't an invoice id (in_…) |
unknown_field | Create, update, send or void an invoice | The body has a field invoices don't have. The message names the nearest one (unitAmount → unit_amount), and field names the one sent |
invalid_customer | Create or update an invoice, List invoices | customer 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_lines | Create or update an invoice | lines is empty, has more than 50 lines, or a line isn't an object or its description isn't text. See field |
missing_description | Create or update an invoice | A line has no description. See field |
invalid_quantity | Create or update an invoice | A line's quantity isn't from 0.01 to 99,999 with up to two decimals |
invalid_amount | Create or update an invoice | A 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_tax | Create or update an invoice | The 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_long | Create or update an invoice | That field isn't text, or a text field is over its limit. See field |
invalid_due_date | Create or update an invoice | due_date isn't a YYYY-MM-DD date from today to two years ahead |
invalid_value | Create or update an invoice | allow_partial, allow_tip or email_receipts isn't true or false |
invalid_min_payment | Create or update an invoice | min_payment is under 1.00 or isn't less than the total |
invalid_reminders | Create or update an invoice | reminders isn't a list of days from -7, -3, -1, 0, 1, 3, 7, 14 and 30 |
invalid_owner | Create or update an invoice, List invoices | owner_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_message | Create or send an invoice | issue or send isn't true or false, or message isn't text, is over 1,000 characters, or was sent without send |
invalid_expected_version | Update an invoice | expected_version isn't a whole number |
not_editable | Update an invoice | payout_wallet_id was sent for an invoice already issued: the wallet is chosen before it's sent |
customer_required | Create or send an invoice | Emailing an invoice (send) needs the customer's name and email; sharing its url needs neither. See field |
invalid_status, invalid_kind | List invoices | status isn't an invoice status or unpaid, or kind isn't invoice or link |
invalid_reason | Void an invoice | reason 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.
| Code | Cause |
|---|---|
invalid_api_key | No 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_token | An 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_disconnected | The 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
| Code | Cause |
|---|---|
merchant_read_only | The 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_disabled | The 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_scope | The 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_payment | Simulate was called on a Live payment. Only Test payments can be simulated |
404 Not Found
| Code | Cause |
|---|---|
not_found | No 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
| Code | Cause |
|---|---|
method_not_allowed | The path exists but does not support this HTTP method. The Allow header lists supported methods. Authentication and access errors still take precedence |
409 Conflict
| Code | Endpoint | Cause |
|---|---|---|
idempotency_conflict | Create a session or invoice | The key was used with a different validated, normalized body. Don't retry: use a new key for a different request |
idempotency_in_progress | Create a session or invoice | Another request with this key hasn't finished yet. Retry the same request with the same key after the Retry-After seconds (1) |
no_payout_wallet | Create a session, payment link, checkout or invoice, issue or send an invoice | Live 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_review | Create a session, payment link, checkout or invoice, issue or send an invoice | Live 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_unusable | Create a payment link or invoice | Live 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_paid | Create | The 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_erased | Create | The store order in order.id belongs to a customer whose details you deleted. Use a new order.id for a new order |
checkout_off | Create from a checkout | The checkout is turned off, so it takes no new sessions. Turn it on in the dashboard first |
checkout_deleted | Create from a checkout | The checkout was deleted. Use another checkout |
commerce_paused | Create, Start | The account has paused taking payments. Nothing was created or started. Applies to payment links, checkouts and invoices too |
unavailable | Start | The 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_providers | Start | No 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_paid | Start | The payment is complete |
held | Start | The money already arrived but didn't pass a check; the dashboard shows the payment as Needs your decision |
failed | Start | The payment was declined. Create a new session |
start_changed | Start | The account's payment settings changed while the session was starting. Nothing was started; try again |
not_started | Simulate | Nobody 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_cancelable | Cancel a session or payment link | The 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_conflict | Report a cancellation or refund | That id was already recorded with a different type or amount. Send a new id for a new event |
duplicate_url | Create a webhook endpoint | That address is already one of your endpoints in this mode. Delete that endpoint, then create it again |
too_many | Create a webhook endpoint | This mode already has 10 endpoints. Remove one first |
payment_link | Change, send, void or delete an invoice | It's a payment link's invoice (kind: "link"): change or cancel it through Payment links |
invoice_changed | Update an invoice | Someone changed the invoice since the version you sent in expected_version. Read it again, then make your change |
invoice_changed, already_paid | Start, for a payment toward an invoice | Less 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_editable | Update an invoice | A 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_issued | Issue an invoice | It's already issued |
invoice_not_payable | Send an invoice | It's paid, void or expired, so there's nothing to send |
email_blocked | Send an invoice | Email 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_suppressed | Send an invoice | The 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_draft | Void an invoice | It's paid, or it's a draft (delete a draft instead) |
not_draft | Delete a draft invoice | It's issued. Void it instead, so its number and history stay |
410 Gone
| Code | Cause |
|---|---|
expired | The session passed its expires_at without being paid |
canceled | The session or payment link was canceled |
invoice_void | Start, for a payment toward an invoice that was voided. Nothing was started |
Size, type and rate
| Status | Code | Cause |
|---|---|---|
| 413 | request_too_large | The body is over 64 KiB |
| 415 | unsupported_media_type | The body isn't sent as Content-Type: application/json |
| 429 | rate_limited | Over 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 |
| 429 | email_too_soon | Send an invoice: it was emailed less than a minute ago. Wait a minute |
| 429 | email_limit | Send 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
| Status | Code | Cause |
|---|---|---|
| 500 | internal | Something failed on our side. Retry with backoff; email support@railbed.com if it continues |
| 502 | network_unavailable | The card network didn't answer while starting. Retry in a minute |
| 503 | misconfigured | Card payments are briefly unavailable. Retry later |
| 503 | payments_paused | Start, 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 |
| 503 | auth_unavailable | An agent's access token couldn't be checked because the sign-in service didn't answer. Retry in a minute with the same token |
| 503 | email_unavailable | Send an invoice: email can't be sent right now. Share the invoice's url with the customer yourself |