> ## Documentation Index > Fetch the complete documentation index at: https://docs.grogov.us/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Error envelope and stable codes. Use `details.code` to handle payment errors. It is the stable, machine-readable identifier for each error. Authentication failures can omit `details` and include only a `message`. ## Error envelope ```json theme={null} { "success": false, "message": "Payment was declined.", "details": { "code": "PAYMENT_DECLINED" } } ``` Some codes add fields to `details`. For example, `VOID_FAILED` and `PARTIAL_REFUND_PENDING` include `retryable` and a `suggestedAction`. `PAYMENT_DECLINED`, `PAYMENT_TIMEOUT` and `PAYMENT_GATEWAY_ERROR` include `id`, the failed payment's ID, when the payment engine returns one for the attempt (some timeouts do not). `GET /payments/{id}` returns that payment: `failed` after a decline or gateway error, and `voided` or `unknown` after a timeout, whose outcome may not be settled. Authentication failures with HTTP status `401` or `403` carry only `message`. ## Error codes | Code | HTTP | Meaning | | - | - | - | | `VALIDATION_ERROR` | 400 | The request is malformed or a field is invalid. See `message` for details | | `PAYMENT_DECLINED` | 402 | The card was declined | | `PAYMENT_BLOCKED` | 403 | Payments are blocked for the case identified by the payment-level `referenceId`. Do not retry | | `PAYMENT_HELD` | 409 | The case identified by the payment-level `referenceId` has a temporary payment hold. Try again later | | `DECLINE_BLOCKED` | 409 | This card was declined recently and is temporarily blocked. Use another card or try again later | | `VELOCITY_LIMIT` | 429 | Too many recent attempts for this case or card. Wait before retrying | | `PAYMENT_NOT_ALLOWED` | 422 | The payment does not meet the portal's payment rules or applicable case restrictions | | `PORTAL_ACCESS_DENIED` | 403 | The portal does not exist or your API account may not use it | | `PAYMENT_NOT_FOUND` | 404 | The payment does not exist or belongs to another API account | | `IDEMPOTENCY_MISMATCH` | 409 | The `Idempotency-Key` was already used with a different request | | `IDEMPOTENCY_IN_PROGRESS` | 409 | A request with this `Idempotency-Key` is still being processed. Retry after `Retry-After` | | `IDEMPOTENCY_RECONCILIATION_REQUIRED` | 409 | An earlier request with this key ended in an unknown state. Contact GroGov before retrying | | `INVALID_STATE` | 422 | The payment cannot be refunded or voided in its current state, or the refund exceeds the remaining amount | | `VOID_FAILED` | 422 | The payment gateway rejected the void. Check `details.suggestedAction` for the next operation | | `INTERNAL_ERROR` | 500 | An unexpected server error | | `CAPTURE_NOT_SUPPORTED` | 501 | Authorize-then-capture is not supported. Payments charge immediately | | `VAULT_NOT_SUPPORTED` | 501 | Storing cards and charging stored vault cards are not supported | | `PAYMENT_GATEWAY_ERROR` | 502 | The payment gateway returned an error. The payment did not succeed | | `PARTIAL_REFUND_PENDING` | 502 | The principal was refunded but the service fee refund failed. Retry the refund | | `GATEWAY_NOT_CONFIGURED` | 503 | The portal has no payment gateway configured | | `IDEMPOTENCY_UNAVAILABLE` | 503 | A request with an `Idempotency-Key` cannot be processed safely right now. Nothing was charged or refunded. Contact GroGov support | | `PAYMENT_TIMEOUT` | 504 | The payment gateway response was missing or unreadable. The outcome is unknown. Check the payment before retrying | ## Handling patterns Case-specific restrictions use the payment-level `referenceId`. This is separate from each line item's `referenceId`. The applicable restrictions depend on the agency's payment configuration. ### `402 PAYMENT_DECLINED` Show `message` to the cardholder. If `details.id` is present, the declined attempt is recorded as a `failed` payment. Do not retry the same card without cardholder action (a new card, a different payment method). ### `403 PAYMENT_BLOCKED` The agency has blocked payments for the case identified by the payment-level `referenceId`. Do not retry the blocked payment. Direct the payer to the agency. ### `504 PAYMENT_TIMEOUT` The outcome is unknown. The card may have been charged. Check the payment status before retrying. If `details.id` is present, call `GET /payments/{id}` with it. Otherwise, list recent payments (`GET /payments` with `portalId` and a `from`/`to` window) to see whether the payment succeeded before trying again. If the original request carried an `Idempotency-Key`, retrying with the same key returns `409 IDEMPOTENCY_RECONCILIATION_REQUIRED` rather than charging twice. See [Idempotency](/guides/idempotency). ### `502 PAYMENT_GATEWAY_ERROR` The gateway reported an error and the payment did not go through. It is safe to retry after a short delay. ### `422 INVALID_STATE` / `VOID_FAILED` The payment does not allow the requested operation. It may already be voided or fully refunded, or the refund may exceed the remaining amount. The `message` states the remaining amount in cents. For `VOID_FAILED`, check `details.suggestedAction`: `"refund"` means the batch has settled and a refund is the correct next step; `"retry_void"` means part of the void succeeded and the void should be retried. ### `502 PARTIAL_REFUND_PENDING` The principal was refunded, but the separate service-fee refund failed. Retry the same refund; `details.remainingRefundableAmountCents` shows what is still outstanding. ### `409` idempotency codes For `IDEMPOTENCY_MISMATCH`, use a new key for a different operation. For `IDEMPOTENCY_IN_PROGRESS`, wait for the interval in `Retry-After` and retry with the same key. For `IDEMPOTENCY_RECONCILIATION_REQUIRED`, follow the [idempotency guidance](/guides/idempotency). ### `501 CAPTURE_NOT_SUPPORTED` / `VAULT_NOT_SUPPORTED` The feature is not supported. Send `capture: "sale"` (the default) and a `card` or `card_token` payment method. ### `503 GATEWAY_NOT_CONFIGURED` The portal has no payment gateway configured. Contact the agency or GroGov support before retrying. ### `503 IDEMPOTENCY_UNAVAILABLE` GroGov cannot record the `Idempotency-Key` for this request right now, so it was refused before anything was charged or refunded. Contact GroGov support; retry the same request with the same key once they confirm it is fixed. ### `403 PORTAL_ACCESS_DENIED` Your API account may not use the `portalId` in the request. Unknown portal IDs return the same code, so the response does not reveal whether a portal exists. Check the `portalId`, and contact GroGov if you expected access. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.