Errors

Errors use conventional HTTP status codes and a single JSON envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_invalid",
    "message": "amount must be a positive decimal string like \"59.90\"",
    "param": "amount",
    "request_id": "req_01J…"
  }
}

• type is a stable category (below). Branch on it in code.
• code is a more specific machine-readable reason. New codes may be added; treat unknown codes by their type.
• param names the offending field when there is one.
• message is for humans and may change — do not parse it.
• request_id matches the Request-Id response header.

Error types

type	Typical status	Meaning	What to do
invalid_request_error	400, 422	Malformed JSON, unknown field, invalid value	Fix the request; do not retry unchanged
authentication_error	401	Missing, invalid or revoked credentials	Check the key and environment
permission_error	403	Authenticated but not allowed (scope, role, store restriction)	Use a key with the right scope
not_found_error	404	The object does not exist or is not visible to your organization	Check the id and environment
conflict_error	409	The object’s state does not allow the action (e.g. cancel after a transfer was observed)	Re-read the object and decide
idempotency_error	409, 422	Idempotency-Key reused with different parameters	Use a new key for a new operation
rate_limit_error	429	Too many requests; see Retry-After	Back off and retry
feature_unavailable_error	403	The feature is not available for your account yet: the account is not activated, payouts are not enabled, the network is disabled or a fiat partner is not in place	Do not retry; the capability is not enabled for your account
api_error	500	Unexpected server error (logged with the request id)	Retry with backoff using the same Idempotency-Key

Unknown fields in request bodies are rejected with invalid_request_error / parameter_unknown rather than silently ignored, so typos surface immediately.

Before your account is activated

Live payments are enabled once your account is verified and approved. Until your account is activated, expect these codes:

code	type	When
live_keys_disabled	feature_unavailable_error	Creating a live API key before your account is activated
live_mode_disabled	feature_unavailable_error	Using live mode, with a live API key or in the dashboard, while your account is not activated
live_processing_unavailable	feature_unavailable_error	Creating a payment intent before live payment processing is enabled for your account
payouts_unavailable	feature_unavailable_error	Requesting a payout before payouts are enabled for your account (they are enabled separately from live payments)
payouts_live_only	invalid_request_error (422)	Managing payout addresses or payouts outside live mode — payouts move real funds
test_mode_disabled	feature_unavailable_error	Creating or using a key that is not live, or creating a payment that is not live. Every key and payment is live: create a live API key once your account is activated

None of them is fixed by retrying. Once your account is activated, the setup checklist in the dashboard marks its live-mode step as complete.

Cross-tenant requests

Requests for another organization’s objects return not_found_error, not permission_error. This avoids confirming that an id exists.

SDK error classes

SDK	Base class	Specific classes
TypeScript	GryphemError	GryphemInvalidRequestError, GryphemAuthenticationError, GryphemPermissionError, GryphemNotFoundError, GryphemConflictError, GryphemIdempotencyError, GryphemRateLimitError, GryphemFeatureUnavailableError, GryphemAPIError, GryphemConnectionError
Python	GryphemError	InvalidRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, IdempotencyError, RateLimitError, FeatureUnavailableError, APIError, APIConnectionError
Go	*gryphempay.Error	inspect Type, Code, Param, Status, RequestID (or gryphempay.ErrorType(err))

Connection errors (connection_error, status 0) mean no response was received; retrying with the same Idempotency-Key is safe.