Errors

Errors come back with an HTTP status and an error object. Branch on type and code: they're stable. message is written for people and may change. param names the field the error is about, and doc_url links to the code's entry below. See API basics for the full shape.

Types

Type	Status	Meaning
`invalid_request_error`	400, 404, 409	The request was wrong: a bad field, an unknown ID, or a conflict with the object's state.
`authentication_error`	401	The API key is missing, invalid or revoked.
`permission_error`	403	The key can't do this.
`card_error`	402	The card or bank declined.
`rate_limit_error`	429	Too many requests. Wait for the time in the Retry-After header.
`processor_error`	502	The payment network didn't answer or refused. The message says what happened and what to do.
`api_error`	500	A problem on our side.

Codes

Code	Status	Meaning
`parameter_missing`	400	A required field is missing, or the request needs a body and had none.
`parameter_invalid`	400	A field has the wrong type or breaks a limit: a decimal or string amount, an ID with the wrong prefix, a value not in the allowed list, metadata over its limits.
`parameter_unknown`	400	The request has a field or query parameter this endpoint doesn't take.
`invalid_json`	400	The body isn't valid JSON.
`invalid_body`	400	The body is JSON but not an object, such as an array or a string.
`resource_missing`	404	No object with that ID exists in this account and mode. A test-mode ID isn't visible to a live key, and the other way round.
`idempotency_key_reused`	409	This `Idempotency-Key` was used in the last 24 hours with different parameters.
`idempotency_key_in_use`	409	The first request with this `Idempotency-Key` is still running.
`card_declined`	402	The card or bank declined. `decline_code` says why when the issuer told us, and `charge` is the failed charge's ID.
`charges_not_enabled`	400	This account can't take live payments yet: its application isn't approved.
`consent_required`	400	An `off_session` charge used a payment method saved without the customer's agreement to be charged later.
`charge_not_capturable`	409	Only a charge in `requires_capture` can be captured.
`charge_not_cancelable`	409	Only an uncaptured authorization can be canceled.
`charge_not_refundable`	409	Only a `succeeded` charge can be refunded.
`charge_already_refunded`	409	The charge has been refunded in full.
`partial_refund_unsupported`	400	Bank account payments can only be refunded in full.
`payment_method_attached`	409	The payment method belongs to another customer.
`processor_unavailable`	502	The payment network didn't answer in time, so the outcome isn't known yet. For a charge or refund, the object exists with status `unknown` or `pending` and resolves on its own, with an event.
`capture_failed`	502	The capture was refused or got no answer.
`cancel_failed`	502	Releasing the authorization was refused or got no answer.
`refund_failed`	502	The refund was refused. The refund object is marked `failed`.
`detach_failed`	502	The saved payment method couldn't be removed. It is still attached.
`invalid_api_key`	401	The key is missing, malformed, revoked or expired.
`account_missing`	401	The key belongs to an account that no longer exists.
`publishable_key`	403	A publishable key (`pk_…`) was used where a secret key is needed.
`secret_key_required`	403	A publishable key tried to save a payment method to a customer, or to allow off-session use.
`account_required`	403	A platform key was used without naming the account to act on.
`insufficient_role`	403	Your role on the account can't do this (dashboard).
`reauthentication_required`	403	Sensitive dashboard actions, such as refunds and new keys, need your second factor within the last ten minutes.
`insufficient_scope`	403	The restricted key (`rk_…`) doesn't have the permission this request needs: read for GET requests, write for the rest.
`product_has_prices`	400	The product has prices, so it may be on invoices or subscriptions, and can’t be deleted.
`invoice_empty`	400	The invoice has no lines, or adds up to nothing, so it can’t be finalized.
`invoice_not_draft`	400	The invoice is finalized, so its lines and settings can’t change any more.
`invoice_not_open`	400	Only an open invoice can be voided or marked uncollectible.
`invoice_has_payments`	400	Payments were made on the invoice, so voiding it would lose track of them.
`test_mode_recipient`	400	In test mode, invoices can only be emailed to people on your team.
`email_failed`	502	The email couldn’t be handed to our mail service. Nothing was marked as sent.
`partial_payments_not_allowed`	400	The invoice must be paid in full, and `amount` was less than what’s owed.
`amount_too_small`	400	The payment is less than the invoice’s `minimum_payment`.
`amount_too_large`	400	The payment is more than the invoice still owes.
`payment_pending`	409	A payment on the invoice hasn’t been confirmed yet, and it may have gone through.
`too_many_payment_attempts`	429	Too many payments on this invoice failed in the last hour.
`installments_total_mismatch`	400	The installments don’t add up to the invoice’s total.
`member_exists`	400	That person is already on the account’s team (dashboard).
`cannot_change_self`	400	Nobody can change their own role or remove themselves from a team (dashboard).
`last_owner`	400	An account always keeps at least one owner (dashboard).
`member_managed_externally`	400	This person’s access comes from Core Labs, which updates it at every sign-in.
`internal_error`	500	Something went wrong on our side.
`processor_not_configured`	500	The account's payment setup isn't finished on our side.
`encryption_not_configured`	500	Webhook endpoints aren't available in this environment yet.
`operation_unspecified`	500	A bug on our side: the endpoint is missing from our API description.

Decline codes

On a card_declined error, decline_code says why, when the issuer told us. Show the customer message, not the code, and ask for another payment method.

Decline code	Meaning
`insufficient_funds`	The card doesn't have enough funds or credit.
`expired_card`	The card has expired.
`incorrect_cvc`	The security code doesn't match.
`card_declined`	The issuer declined and didn't say why.