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"
  }
}

Field	Type	Description
`type`	string	Error category (see Error Types below).
`code`	string	Machine-readable error code.
`message`	string	Human-readable description.
`param`	string	The request parameter that caused the error (if applicable).
`connector_code`	string	Raw error code from the payment processor (for connector errors).
`request_id`	string	Unique identifier for the request (use in support tickets).
`debug`	string	Additional debug information (only with X-Debug header and admin role).

Error Types

Type	HTTP Status	Description
`invalid_request_error`	400, 404, 409	The request was malformed, missing required parameters, or references a resource that does not exist.
`authentication_error`	401	No valid API key was provided, or the key has been revoked.
`authorization_error`	403	The API key does not have permission for the requested operation.
`rate_limit_error`	429	Too many requests. Back off and retry after the indicated period.
`validation_error`	400	Request parameters failed validation rules.
`connector_error`	502	The downstream payment processor returned an error.
`idempotency_error`	409, 422	Conflict with idempotency key usage.
`timeout_error`	504	The payment processor did not respond within the allowed time.

Error Codes Reference

Code	Type	HTTP	Description
`invalid_param`	`invalid_request_error`	400	A request parameter is missing or invalid.
`invalid_request`	`invalid_request_error`	400	The request body or format is invalid.
`missing_idempotency_key`	`invalid_request_error`	400	The Idempotency-Key header is required but was not provided.
`payment_intent_not_found`	`invalid_request_error`	404	The specified PaymentIntent does not exist.
`invalid_state_transition`	`invalid_request_error`	409	The PaymentIntent is not in the correct status for this operation.
`refund_exceeds_amount`	`invalid_request_error`	400	The refund amount exceeds the remaining refundable balance.
`authentication_required`	`authentication_error`	401	No API key was provided in the Authorization header.
`invalid_api_key`	`authentication_error`	401	The API key is invalid or has been revoked.
`authentication_failed`	`authentication_error`	401	Authentication credentials are incorrect.
`insufficient_permissions`	`authorization_error`	403	The API key does not have the required role or scope.
`rate_limit_exceeded`	`rate_limit_error`	429	Rate limit exceeded. Retry after the indicated number of seconds.
`validation_failed`	`validation_error`	400	One or more request parameters failed validation.
`connector_error`	`connector_error`	502	The payment processor returned an error. Check `connector_code` for details.
`idempotency_conflict`	`idempotency_error`	409	Another request with this idempotency key is currently being processed.
`idempotency_param_mismatch`	`idempotency_error`	422	This idempotency key was already used with different request parameters.
`idempotency_error`	`idempotency_error`	409	General idempotency conflict.
`connector_timeout`	`timeout_error`	504	The payment processor did not respond within the allowed time.
`timeout`	`timeout_error`	504	The 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

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