Skip to Content
Error Codes

Error Codes

All API errors follow a standard envelope format. The HTTP status code indicates the error category, and the response body provides details.

Error Response Structure

{ "error": { "type": "invalid_request_error", "code": "invalid_param", "message": "Amount must be a positive integer in cents.", "param": "amount", "request_id": "req_abc123" } }
FieldTypeDescription
typestringError category (see Error Types below).
codestringMachine-readable error code.
messagestringHuman-readable description.
paramstringThe request parameter that caused the error (if applicable).
connector_codestringRaw error code from the payment processor (for connector errors).
request_idstringUnique identifier for the request (use in support tickets).
debugstringAdditional debug information (only with X-Debug header and admin role).

Error Types

TypeHTTP StatusDescription
invalid_request_error400, 404, 409The request was malformed, missing required parameters, or references a resource that does not exist.
authentication_error401No valid API key was provided, or the key has been revoked.
authorization_error403The API key does not have permission for the requested operation.
rate_limit_error429Too many requests. Back off and retry after the indicated period.
validation_error400Request parameters failed validation rules.
connector_error502The downstream payment processor returned an error.
idempotency_error409, 422Conflict with idempotency key usage.
timeout_error504The payment processor did not respond within the allowed time.

Error Codes Reference

CodeTypeHTTPDescription
invalid_paraminvalid_request_error400A request parameter is missing or invalid.
invalid_requestinvalid_request_error400The request body or format is invalid.
missing_idempotency_keyinvalid_request_error400The Idempotency-Key header is required but was not provided.
payment_intent_not_foundinvalid_request_error404The specified PaymentIntent does not exist.
invalid_state_transitioninvalid_request_error409The PaymentIntent is not in the correct status for this operation.
refund_exceeds_amountinvalid_request_error400The refund amount exceeds the remaining refundable balance.
authentication_requiredauthentication_error401No API key was provided in the Authorization header.
invalid_api_keyauthentication_error401The API key is invalid or has been revoked.
authentication_failedauthentication_error401Authentication credentials are incorrect.
insufficient_permissionsauthorization_error403The API key does not have the required role or scope.
rate_limit_exceededrate_limit_error429Rate limit exceeded. Retry after the indicated number of seconds.
validation_failedvalidation_error400One or more request parameters failed validation.
connector_errorconnector_error502The payment processor returned an error. Check connector_code for details.
idempotency_conflictidempotency_error409Another request with this idempotency key is currently being processed.
idempotency_param_mismatchidempotency_error422This idempotency key was already used with different request parameters.
idempotency_erroridempotency_error409General idempotency conflict.
connector_timeouttimeout_error504The payment processor did not respond within the allowed time.
timeouttimeout_error504The request timed out.

Handling Errors

Check the type field first to determine the error category, then use code for specific handling:

try { await client.payments.authorize(params); } catch (err) { if (err instanceof GatelithixError) { switch (err.type) { case "authentication_error": // Check API key configuration break; case "invalid_request_error": if (err.code === "payment_intent_not_found") { // Payment not found -- check the ID } else if (err.code === "invalid_state_transition") { // Payment is in wrong status for this operation } else { // Fix the request parameter indicated by err.param } break; case "rate_limit_error": // Back off and retry break; case "connector_error": // Processor issue -- check err.connector_code break; case "timeout_error": // Retry with the same idempotency key break; } } }

HTTP Status Code Summary

StatusMeaning
200Success
201Created
400Bad request (invalid parameters)
401Unauthorized (missing or invalid API key)
403Forbidden (insufficient permissions)
404Not found
409Conflict (state transition or idempotency)
422Unprocessable (idempotency parameter mismatch)
429Rate limit exceeded
502Connector error (processor failure)
504Timeout (processor did not respond)

Connector account errors (since v2.3)

Version 2.3 introduced the connector account model and 8 new error codes that surface through the standard error envelope. Every row below links back to the Migration Guide — read it if you’re upgrading from v2.2.x.

CodeHTTPDescriptionFix
connector_account_required400The routed merchant has no resolvable default connector account for the (connector, mode, key_kind) triple, and the caller did not specify one. See migration guide.Create a default account (admin API), or pass connector_account in the request body / X-Connector-Account header. The response includes available_accounts when authenticated for the correct merchant.
connector_account_not_found404The connector_account short_id does not exist, OR exists but is owned by a different merchant (anti-enumeration — the two cases are collapsed into one 404). See migration guide.Verify the short_id is owned by the authenticated merchant.
connector_account_inactive409The target connector account exists and is owned by the merchant but has is_active=false. See migration guide.Create a new active account — deactivated accounts cannot be reactivated.
connector_account_mismatch409The override connector_account resolves to an account owned by the merchant but for a different connector than the request routed to.Pass a connector_account that matches the routed connector, or remove the override.
connector_account_mode_mismatch409The override connector_account resolves to an account owned by the merchant but for a different mode (live vs test) than the request.Use a connector account whose mode matches the request mode.
invalid_connector_account400The body connector_account field or X-Connector-Account header value is neither a valid short_id nor a valid UUID. The raw offending value is never echoed in the response.Send a value matching the short_id pattern (cac_...) or a canonical UUID.
connector_account_ambiguous400Both the body connector_account and X-Connector-Account header are set and disagree. See migration guide.Pick one. Body wins when both are set and agree.
connector_account_override_forbidden400A capture, refund, or void operation supplied a connector_account different from the one that settled the originating authorize/sale. Cross-account settlement is a hard invariant. See migration guide.Drop the connector_account override on capture/refund/void — follow-on ops inherit the originating account automatically.

Tracked for v2.4: connector_account_default_conflict, connector_account_label_conflict, and originating_account_unavailable have store-level enforcement (DB partial unique indexes for default/label, resolver lookup for refund-time availability) but do not yet have dedicated error.code values. These conditions currently surface as generic 409 errors with descriptive messages.