Error codes

The API key exists but is past its expiration time.

Fix: Create or use an active API key for the target mode and merchant, then retry.

The API key is not usable for its stored payment-mode binding.

Fix: Create or use an API key whose mode matches the target environment, then retry.

No API key matches the provided credential.

Fix: Check the API key value or create a new API key, then retry.

The request did not include an API key or accepted bearer credential.

Fix: Send a Flint API key in X-API-Key or as Authorization: Bearer <API_KEY>, then retry.

The API key exists but has been revoked.

Fix: Create or use an active API key for the target mode and merchant, then retry.

The API key is bound to a sandbox that is missing, archived, inactive, or mode-incompatible.

Fix: Create or use a sandbox-bound test key for an active sandbox, then retry.

The API key uses a legacy or unsupported scope grant.

Fix: Create a new API key with explicit public API scopes, then retry.

The request could not be authenticated.

Fix: Send a valid Flint API key, partner install token, checkout session credential, or dashboard session for this route, then retry.

The authenticated caller is not authorized for this operation.

Fix: Use credentials with access to the target merchant, environment, route, and scope, then retry.

A public resource referenced another resource that could not be resolved during expansion.

Fix: Contact support with the request_id; this indicates a Flint data-integrity defect.

The demo session key cannot access this route.

Fix: Use a merchant API key for this route, or call a route supported by demo sessions.

A service required for an accepted expansion is unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

The requested expansion exceeded a route fanout or response-size limit.

Fix: Request fewer expansions or use follow-up read/list endpoints.

Flint could not resolve an accepted expansion.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

A request with the same idempotency key is still in progress.

Fix: Wait briefly and retry with the same idempotency key.

The idempotency key was reused with a different request body.

Fix: Use the original request body with this idempotency key, or generate a new idempotency key for a new operation.

The API key is missing a required scope.

Fix: Create or use an API key with the required scope, then retry the request.

Flint returned an internal server error.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

The API key credential is malformed or invalid.

Fix: Check the API key value or create a new API key, then retry.

The Authorization header is malformed or uses an unsupported credential.

Fix: Send a Flint API key or partner install token as Authorization: Bearer <token>, or use X-API-Key for API keys.

The request included an invalid or unsupported expand path.

Fix: Fix or remove the requested expand path; use only supported values documented for the route.

The request included an invalid or past expiration timestamp.

Fix: Send expires_at as a future RFC3339 timestamp, or omit it for a non-expiring key.

The request payload contains a field with the wrong JSON type.

Fix: Send the field using the documented JSON type, then retry with the same idempotency key if this was the same logical operation.

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry with the same idempotency key if this was the same logical operation.

The partner install token is invalid or expired.

Fix: Refresh or reinstall the partner app authorization, then retry with a valid partner install token.

The merchant is not ready for this operation.

Fix: Complete the required merchant readiness or onboarding action before retrying.

The merchant is not ready for this operation.

Fix: Complete the required merchant readiness or onboarding action before retrying.

The route exists, but does not support the requested HTTP method.

Fix: Use one of the methods supported by the route, as listed in the Allow header.

The payment intent is attached to an order and cannot be managed through the generic payment-intent action route.

Fix: Use the order payment flow to confirm, capture, or cancel this payment intent.

The request exceeded the configured rate limit.

Fix: Retry with exponential backoff and jitter. Use the Retry-After header when present.

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

The request timed out before Flint could complete it.

Fix: Retry with exponential backoff. Contact support with the request_id if the timeout persists.

The requested resource could not be found for the authenticated merchant and environment.

Fix: Check the resource ID, mode, and merchant context, then retry.

No public API route matched the request path.

Fix: Check the path and remove unsupported trailing slashes or legacy routes before retrying.

The test-mode API key is not bound to a sandbox.

Fix: Create or use a sandbox-bound test key for the sandbox this request should target, then retry.

A service required to complete the request is temporarily unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry with the same idempotency key if this was the same logical operation.

The request body used an unsupported Content-Type.

Fix: Send JSON request bodies with Content-Type: application/json, then retry.

The request included a query parameter this endpoint does not support.

Fix: Remove the unsupported query parameter or use a documented accepted expand encoding.

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry with the same idempotency key if this was the same logical operation.