Error Handling

The API uses standard HTTP status codes and returns structured error responses.

HTTP status codes

Error response format

All errors return a JSON object with message and code fields:

{
  "message": "A human-readable description of the error.",
  "code": 3
}

The code field is the underlying gRPC status code number.

Validation errors

Invalid request parameters return HTTP 400 with a message indicating the problematic field:

HTTP/1.1 400 Bad Request

{
  "message": "Invalid argument at \"email\": This must be a valid email address.",
  "code": 3
}

Resource not found

Requesting a resource that doesn't exist returns HTTP 404:

HTTP/1.1 404 Not Found

{
  "message": "Resource \"accounts/acct_ACCOUNT_ID/customers/cus_INVALID\" (of type \"Customer\") not found.",
  "code": 5
}

Idempotency errors

If two concurrent requests use the same idempotency key, the second request returns HTTP 409:

HTTP/1.1 409 Conflict

{
  "message": "Another request with idempotency key \"fb_idem_key_...\" is in progress.",
  "code": 10
}

If a request reuses an idempotency key with a different request body, the API returns HTTP 400:

HTTP/1.1 400 Bad Request

{
  "message": "Mismatch between stored request body for idempotency key and received request body. When retrying idempotent requests, please ensure the request body is identical.",
  "code": 3
}

Payment errors

When a payment fails, the payment intent's response includes a payment_error object with more detail:

Failure codes

Decline codes

When the failure code is PAYMENT_METHOD_PROVIDER_DECLINE, a more specific decline_code is included:

Payment error structure

{
  "code": "PAYMENT_METHOD_PROVIDER_DECLINE",
  "decline_code": "INSUFFICIENT_FUNDS",
  "message": "The card has insufficient funds.",
  "payment_method": "accounts/acct_YOUR_ACCOUNT/payment-methods/pm_PAYMENT_METHOD_ID"
}