> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/en/api-reference/errors.md). # Errors Error format, HTTP statuses and the list of error codes with how to handle each one. Every error has this shape: ```json { "error": { "type": "invalid_request_error", "code": "refund_exceeds_remaining", "message": "Refund amount exceeds what can still be refunded (fees are not refundable).", "param": "amount" } } ``` * `type`: the error category, which determines the HTTP status. * `code`: the specific code, to use in your code. * `message`: in English, with no sensitive information. Don't compare this string in your code, because it may change. * `param`: the field that caused the error (if any), for example `items[0].quantity`. * `decline_code`: only present when a card is declined and the reason is known. ## Error types | `type` | HTTP | Meaning | | ----------------------- | ------------- | ---------------------------------------------------- | | `invalid_request_error` | 400, 404, 409 | Invalid request, not found, or a state conflict | | `authentication_error` | 401 | Wrong key or client secret | | `card_error` | 402 | Card declined or payment failed | | `rate_limit_error` | 429 | Over the limit, see the `Retry-After` header | | `api_error` | 500, 502 | Error on the Loomgate side or in the payment network | The API doesn't use 403: a suspended or unapproved account gets a 400. ## Error codes | `code` | HTTP | Meaning | What to do | | -------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `validation_error` | 400 | Malformed request: missing field, wrong type, unknown field, broken JSON | Fix according to `param` | | `invalid_amount` | 400 | The amount is not a positive integer | Fix the request | | `amount_too_small` | 400 | The buyer's total is below 100, or the fees are equal to or greater than the amount when you pay the fees | Increase the amount | | `amount_too_large` | 400 | The total is over 99,999,999 | Split the payment | | `unsupported_currency` | 400 | A currency other than `usd`, `eur` | Fix the request | | `invalid_billing_details` | 400 | The buyer's billing details are missing or invalid | Fix according to `param` | | `invalid_payment_details` | 400 | Items, buyer, order reference or address break the rules | Fix according to `param` | | `payment_details_missing` | 400 | Confirmation while the payment is still missing the buyer, order reference or shipping address | Update the payment, then confirm again | | `non_physical_goods_not_allowed` | 400 | The account is not allowed to sell non-physical goods | Contact Loomgate or your reseller | | `payment_intent_not_pending` | 400 | The payment is complete or canceled, or has used all its attempts | Create a new payment | | `payment_not_refundable` | 400 | The payment has not succeeded, or the payment network refused the refund | Check the payment status | | `refund_exceeds_remaining` | 400 | More than `amount_refundable` | Lower the refund amount | | `merchant_suspended` | 400 | The account is suspended | Contact Loomgate | | `merchant_not_approved` | 400 | The account has not been approved yet | Wait for approval | | `invalid_api_key` | 401 | Missing or wrong API key | Check the `Authorization` header | | `api_key_revoked` | 401 | The key has been revoked | Use a new key | | `invalid_client_secret` | 401 | Wrong `client_secret` | Check which payment you are using | | `payment_method_declined` | 402 | Card declined | Release, ask the buyer to use another card | | `payment_failed` | 402 | The payment failed (for example 3-D Secure did not pass) | Release, invite the buyer to try again | | `not_found` | 404 | The route or object does not exist | Check the URL | | `payment_intent_not_found` | 404 | No such payment in your account | Check the id and the key | | `refund_not_found` | 404 | No such refund | Check the id | | `idempotency_key_reused` | 409 | The key was already used with a different body or on another route | Use a new key | | `payment_intent_updated` | 409 | The amount changed since the card form loaded; nothing was charged | Reload the form, have the buyer confirm again | | `rate_limited` | 429 | Too many requests or attempts | Wait `Retry-After` seconds | | `internal_error` | 500 | Error on the Loomgate side | Retry later (with an `Idempotency-Key`) | | `fee_plan_not_configured` | 500 | The account has no fee schedule | Contact Loomgate | | `provider_error` | 502 | The payment network could not process the request | Retry later; for confirmations, retrieve the payment first | ## When to retry * **429, 500, 502, timeouts, network errors**: retry with the same `Idempotency-Key`. For routes without idempotency (confirm, update), retrieve the object first to find out whether the operation happened. * **400, 401, 404, 409**: retrying the same request will fail again; fix the cause first. * **402**: don't automatically retry the same card; release and let the buyer decide. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.loomgate.io/en/api-reference/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.