Errors
The error envelope and shared error code catalogue.
Errors use a JSON envelope:
{
"error": {
"code": "invalid_request",
"message": "The request is invalid.",
"docs_url": "https://docs.hermos.com/api/v1/errors#invalid-request"
},
"request_id": "123e4567-e89b-42d3-a456-426614174000"
}Use error.code for programmatic handling. message is a canonical human-readable
message. docs_url is optional in the contract; its current default is shown above.
The API also returns the server-generated correlation ID in X-Request-Id.
Unknown errors return internal_error without exception messages or stacks.
Optional error.details contains up to 20 entries with a safe path array and a rule.
Detail rules can select a more specific HTTP status than the code's default below.
One code is the exception: setup_attempt_superseded carries an object,
{ "current_attempt": <number>, "same_sheet": <boolean> }, instead of a list.
In-progress idempotent conflicts can include operation_id and checkout_instance_id.
Duplicate purchases can include subscription_id and manage_url. Expired feed cursors
use oldest_sequence with the cursor_expired detail rule. Those fields are contract
support; the corresponding resource endpoints are not yet available.
The shared catalogue includes codes for endpoints still being added. A code's presence does not imply that its corresponding endpoint is available.
| Code | Default HTTP status |
|---|---|
account_binding_conflict | 409 |
account_binding_no_purchase | 422 |
account_binding_proof_invalid | 422 |
account_binding_proof_already_claimed | 409 |
account_binding_proof_not_confirmed | 409 |
credit_amount_invalid | 400 |
credit_not_available | 409 |
revision_scope_too_broad | 422 |
notice_unsupported_shape | 422 |
custom_domain_unavailable | 400 |
preview_unavailable | 404 |
keep_access_needs_full_refund | 400 |
keep_access_chargeback_lost | 400 |
invalid_request | 400 |
invalid_parameter | 400 |
validation_error | 400 |
unauthorized | 401 |
forbidden | 403 |
product_scope_unsupported | 403 |
not_found | 404 |
method_not_allowed | 405 |
conflict | 409 |
idempotency_key_reused | 409 |
payload_too_large | 413 |
rate_limited | 429 |
internal_error | 500 |
service_unavailable | 503 |
operations_unavailable | 503 |
limit_exceeded | 403 |
approval_denied | 403 |
precondition_failed | 400 |
processor_unavailable | 503 |
processor_declined | 402 |
idempotency_key_required | 400 |
invalid_cursor | 400 |
duplicate_purchase | 409 |
setup_attempt_superseded | 409 |
receipt_not_available | 422 |
receipt_no_recipient | 422 |
receipt_recipient_suppressed | 422 |
receipt_resend_too_soon | 429 |
account-binding-conflict
The customer or app account already has a conflicting binding for this product (409). Read the existing binding before retrying; bindings cannot be reassigned.
account-binding-no-purchase
The customer has no purchase for the requested product (422).
account-binding-proof-invalid
The mailbox proof is invalid, expired, already used, or does not match this binding (422). Request a new proof for the same customer, product, and app account.
account-binding-proof-already-claimed
The mailbox proof has already been claimed (409). A proof is returned only once.
account-binding-proof-not-confirmed
The buyer has not confirmed the mailbox link yet (409). Wait for confirmation before claiming.
credit-amount-invalid
Enter an integer amount above zero and no more than 1,000,000 minor units in the subscription's currency. This flat cap also covers metered, tiered and multi-price subscriptions, where there is no single recurring price to multiply.
credit-not-available
The subscription has ended or has no usable Stripe processor customer, account, or currency. Credit is customer account credit applied to future invoices.
revision-scope-too-broad
A merchant read of GET /v1/entitlements naming only one of customer or subject
returns revision_scope_too_broad (422) when its summed counters reach 2^32 or its
packed revision is not a safe integer. Pass both customer and subject to narrow
the read. Reads with neither selector are already rejected by validation.
Fully narrowed merchant reads and all session reads retain the internal invariant
error if the revision is exhausted.
product-scope-unsupported
This endpoint does not support product-scoped API keys. A key limited to specific products can currently read entitlements for its granted products.
Invalid parameter
invalid_parameter (400) means a query parameter could not be read, before any data is looked up. It is a separate code from validation_error by design: report filters are checked here, not as body validation.
| Rule | Field | Meaning |
|---|---|---|
invalid_format | query.product, query.plans | The value is not a product or plan ID. |
too_big | query.plans | More than 50 distinct plan IDs. |
A well-formed ID that belongs to another account is not an error; the report returns zeros.
Customer evidence intake
Activity and communication payload validation returns validation_error (400).
The following detail rules identify the field or limit to correct. A failed batch
stores no events. Resolve the cause before retrying the request.
| Detail rule | Code | HTTP status | Meaning |
|---|---|---|---|
keys_only_scope | forbidden | 403 | Activity ingestion requires a secret or restricted API key with customer_activity:write. |
product_restricted_member | forbidden | 403 | Product-restricted members cannot read customer activity or record communications. Refunds require every payment product in the member's grant. These checks also apply to cached replays. |
product_limit | forbidden | 403 | A product-restricted member is refused on company routes until per-product grants exist, including cached replays. |
occurred_at_out_of_range | validation_error | 400 | The event or communication is over 400 days old or over five minutes in the future. |
activity_product_mismatch | validation_error | 400 | The product differs from the referenced entitlement's product. |
activity_needs_ip_or_device | validation_error | 400 | A login or access event needs an IP address or device ID. |
activity_detail_invalid | validation_error | 400 | Detail must be a flat object of string values. |
activity_detail_too_large | validation_error | 400 | Canonical detail JSON exceeds 2,048 UTF-8 bytes. |
activity_customer_daily_cap | rate_limited | 429 | New events exceed 5,000 per customer per UTC day. |
customer_erasure_requested | conflict | 409 | The customer is deleted or evidence intake is fenced for erasure. |
identifier_conflict | conflict | 409 | The identifier already belongs to another customer in this company and mode. |
communication_body_too_large | validation_error | 400 | The body exceeds 65,536 UTF-8 bytes. |
communication_subject_too_long | validation_error | 400 | The subject exceeds 998 Unicode code points. |
Unknown or inaccessible customer, product, entitlement, payment, or subscription
references return not_found (404). Invalid payload shapes use invalid_value;
invalid IP addresses use invalid_format, both under validation_error (400).
restart_in_progress is a 409 conflict detail rule when a live restart checkout already exists for the subscription. The restart accept and resume routes also return these 409 conflict detail rules:
- Eligibility and offer:
not_ended,old_balance_pending,restart_not_latest,composed_offer_unsupported_on_follow_on,notice_unsupported_shape,restart_price_unresolved,restart_offer_unresolved,restart_kept_price_unavailable. - Charge admission:
restart_customer_balance_present,restart_pending_invoice_items,restart_processor_unavailable,restart_below_minimum_charge,restart_zero_price_unsupported,restart_account_currency_unsupported. - Acceptance:
restart_terms_changed,restart_acceptance_required.
Restart requires a customer billing session with the restart flow. A foreign customer's subscription remains not_found; a pending or ambiguous collection cannot release a new charge attempt.
Checkout abandonment returns 409 conflict with detail rule submission_in_progress
when a submission, processor Session, checkout/collection operation or unresolved purchase
may still collect. The checkout and its claims remain unchanged. checkout_already_open
means another subject has a live checkout in this browser; its details include only
expires_at. Plain opens never return an organisation-bound form or receipt.
Subject/product abandonment returns 409 conflict with rule multiple_checkouts_open when
more than one live checkout matches; none is changed. A missing product, missing live instance,
or inaccessible company/mode returns the same 404 not_found. By-ID abandonment returns 200
unchanged for an already-terminal checkout, including one with running collection work.
Refund creation
Refund refusals use a detail rule under the error code shown below. An
unavailable operations runtime returns operations_unavailable (503), and an
unknown or foreign payment returns not_found (404).
| Detail rule | Code | HTTP status | Meaning |
|---|---|---|---|
agent_refund_not_available | forbidden | 403 | Agent principals and agent keys cannot create refunds. |
named_lines_not_available | precondition_failed | 409 | Named refund lines are not supported yet. |
fee_refund_not_ready | precondition_failed | 409 | Fee-bearing payments are not supported yet. |
payment_plan_refund_not_ready | precondition_failed | 409 | Installment or schedule-managed payment plan. |
refund_lineage_unproven | precondition_failed | 409 | Hermos invoice lineage cannot prove the captured payment. |
payment_not_refundable | precondition_failed | 409 | Payment is not a succeeded Stripe charge. |
account_unreachable | precondition_failed | 409 | The original processor account cannot be used. |
refunds_not_enabled | precondition_failed | 409 | Tenant and mode are not enabled. |
refund_exceeds_capacity | precondition_failed | 409 | Requested amount exceeds captured capacity. |
refund_evidence_pending | conflict | 409 | Payment details are still processing; try again in a few minutes. |
refund_evidence_stalled | conflict | 409 | Payment syncing could not finish. Our team has been alerted; contact support if this is not resolved soon. |
refund_capacity_held | conflict | 409 | A held dispute temporarily reduces capacity. |
refund_held_for_review | conflict | 409 | An earlier refund on this payment is stuck and waiting for support review. |
refund_plan_inconsistent | conflict | 409 | Recorded operation cannot be reconciled safely. |
idempotency_key_abandoned | conflict | 409 | The prior journal intent was abandoned. |
refund_currency_mismatch | invalid_request | 422 | Amount currency differs from payment currency. |
Changing the next charge date
POST /v1/subscriptions/{subscription}/next_charge_date accepts an RFC 3339 UTC timestamp, such as 2026-12-01T00:00:00Z.
Refusals return HTTP 409 with code conflict and one of these detail rules:
| Rule | Meaning |
|---|---|
next_charge_date_not_later | Choose a date strictly later than the current trial end and next renewal or item period end. |
next_charge_date_too_far | Choose a date no more than 90 days from now. |
subscription_not_reschedulable | Only active or trialing Stripe subscriptions without scheduled cancellation or paused collection can be moved. |
subscription_cycle_invoice_pending | A subscription renewal invoice is open or draft with an amount remaining. Retry after the renewal settles. |
The intervening days are free. No charge, proration credit or debit, or invoice is created for the gap.
Payment re-check refusals
| Rule | HTTP status | Meaning |
|---|---|---|
recheck_takes_no_values | 400 | A re-check accepts only an optional reason, up to 500 characters. Remove all other fields. |
recheck_not_available | 409 | This payment has no readable Stripe charge. A re-check cannot be requested for this payment. |
These are detail rules under invalid_request and precondition_failed, respectively.
A re-check requests ordinary sync and moves no money. Poll its status until sync finishes;
pending never means that the stored payment matches Stripe.
Receipt resend
Seller receipt resends ignore the automatic receipt switch. When a receipt is not
available, the detail rule identifies read_only, refunded, disputed,
test_mode_recipient, or recipient_changed where it applies.
| Code | HTTP status | Meaning |
|---|---|---|
receipt_not_available | 422 | This payment has no receipt to send. Only succeeded payments linked to a paid invoice have receipts. |
receipt_recipient_suppressed | 422 | Receipt emails cannot be delivered to this address. Suppressed, bounced and complained addresses cannot receive a resend. |
receipt_no_recipient | 422 | This customer has no email address to send a receipt to. Add an email address to the customer before retrying. |
receipt_resend_too_soon | 429 | A receipt was just sent for this payment. Seller resends have a ten-minute cooldown per payment; try again in a few minutes. |
receipt-not-available
Only succeeded payments linked to a paid invoice have receipts. Confirm the payment and invoice state before requesting a resend.
receipt-no-recipient
Add an email address to the customer before retrying the receipt resend.
receipt-recipient-suppressed
Suppressed, bounced and complained addresses cannot receive a receipt resend. Resolve the recipient's delivery status before retrying.
receipt-resend-too-soon
Seller receipt resends have a ten-minute cooldown per payment. Wait for that cooldown before requesting another resend.
access-reduction-required
POST /v1/refunds returns access_reduction_required (400) when a partial refund
has no explicit access_reduction choice. A refund is partial when it is less
than the payment amount minus settled refunds and confirmed losses. While another
refund, held dispute, or operation hold is still unconfirmed, refunding the
available remainder counts as partial, including when amount is omitted.
Send access_reduction: "all" to end access or access_reduction: "none" to keep
access. A legacy access: "keep" request for that whole remainder also returns
this rule. With no unconfirmed holds, a full refund defaults to access: "end".
keep-access-needs-full-refund
POST /v1/refunds returns keep_access_needs_full_refund (400) when access: "keep"
is sent without access_reduction and with an amount smaller than the available
remainder. Send an explicit access_reduction: "none" to keep access for a partial
refund, or access_reduction: "all" to end it. If you also send access, it must
match: "keep" with "none", or "end" with "all". Refunding the whole available
remainder while money is still unconfirmed returns access_reduction_required
instead when the explicit choice is missing.
keep-access-chargeback-lost
POST /v1/refunds returns keep_access_chargeback_lost (400), including dry-run
previews, when access: "keep" is requested after a lost dispute or an effective
bank return. Message: "The buyer won a chargeback on this payment, so their access
has already ended." Use access: "end" to refund any remaining available amount.
Open and won disputes do not trigger this refusal.
Free-period retention offers
Each subscription can receive one free month over its whole life. After a
grantSubscriptionFreePeriod operation succeeds, new free_period requests return
retention_free_period_already_used (conflict, 409) before another operation is
recorded, and the portal omits the offer. Replaying the original idempotency key
still returns the original operation. Failed, denied, expired, or stale grants do
not consume the offer.
free_period is a retention_offer. Existing discounts are checked asynchronously:
acceptance returns 202, then the operation fails with discount_present (conflict, 409)
without changing the subscription. A reserved coupon with incompatible terms fails
with free_period_coupon_conflict (conflict, 409), before the subscription mutation.
The coupon must be 100% off, once, valid, marked hermos=free_period, with no product,
currency, fixed-amount, redemption-count, or redemption-deadline restrictions.
The next renewal is paid-zero and access remains prepaid; no trial is created.
Requests at or within one hour of the next renewal fail with too_close_to_renewal
(conflict, 409), before an operation is recorded.
Accepted limitation: a discount added in the processor dashboard between the preflight
read and the mutation is replaced and lost. Recovery after coupon consumption requires
attributed renewal-discount evidence; missing evidence leaves the operation ambiguous.