Hermos API
Concepts

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.

CodeDefault HTTP status
account_binding_conflict409
account_binding_no_purchase422
account_binding_proof_invalid422
account_binding_proof_already_claimed409
account_binding_proof_not_confirmed409
credit_amount_invalid400
credit_not_available409
revision_scope_too_broad422
notice_unsupported_shape422
custom_domain_unavailable400
preview_unavailable404
keep_access_needs_full_refund400
keep_access_chargeback_lost400
invalid_request400
invalid_parameter400
validation_error400
unauthorized401
forbidden403
product_scope_unsupported403
not_found404
method_not_allowed405
conflict409
idempotency_key_reused409
payload_too_large413
rate_limited429
internal_error500
service_unavailable503
operations_unavailable503
limit_exceeded403
approval_denied403
precondition_failed400
processor_unavailable503
processor_declined402
idempotency_key_required400
invalid_cursor400
duplicate_purchase409
setup_attempt_superseded409
receipt_not_available422
receipt_no_recipient422
receipt_recipient_suppressed422
receipt_resend_too_soon429

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.

RuleFieldMeaning
invalid_formatquery.product, query.plansThe value is not a product or plan ID.
too_bigquery.plansMore 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 ruleCodeHTTP statusMeaning
keys_only_scopeforbidden403Activity ingestion requires a secret or restricted API key with customer_activity:write.
product_restricted_memberforbidden403Product-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_limitforbidden403A product-restricted member is refused on company routes until per-product grants exist, including cached replays.
occurred_at_out_of_rangevalidation_error400The event or communication is over 400 days old or over five minutes in the future.
activity_product_mismatchvalidation_error400The product differs from the referenced entitlement's product.
activity_needs_ip_or_devicevalidation_error400A login or access event needs an IP address or device ID.
activity_detail_invalidvalidation_error400Detail must be a flat object of string values.
activity_detail_too_largevalidation_error400Canonical detail JSON exceeds 2,048 UTF-8 bytes.
activity_customer_daily_caprate_limited429New events exceed 5,000 per customer per UTC day.
customer_erasure_requestedconflict409The customer is deleted or evidence intake is fenced for erasure.
identifier_conflictconflict409The identifier already belongs to another customer in this company and mode.
communication_body_too_largevalidation_error400The body exceeds 65,536 UTF-8 bytes.
communication_subject_too_longvalidation_error400The 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 ruleCodeHTTP statusMeaning
agent_refund_not_availableforbidden403Agent principals and agent keys cannot create refunds.
named_lines_not_availableprecondition_failed409Named refund lines are not supported yet.
fee_refund_not_readyprecondition_failed409Fee-bearing payments are not supported yet.
payment_plan_refund_not_readyprecondition_failed409Installment or schedule-managed payment plan.
refund_lineage_unprovenprecondition_failed409Hermos invoice lineage cannot prove the captured payment.
payment_not_refundableprecondition_failed409Payment is not a succeeded Stripe charge.
account_unreachableprecondition_failed409The original processor account cannot be used.
refunds_not_enabledprecondition_failed409Tenant and mode are not enabled.
refund_exceeds_capacityprecondition_failed409Requested amount exceeds captured capacity.
refund_evidence_pendingconflict409Payment details are still processing; try again in a few minutes.
refund_evidence_stalledconflict409Payment syncing could not finish. Our team has been alerted; contact support if this is not resolved soon.
refund_capacity_heldconflict409A held dispute temporarily reduces capacity.
refund_held_for_reviewconflict409An earlier refund on this payment is stuck and waiting for support review.
refund_plan_inconsistentconflict409Recorded operation cannot be reconciled safely.
idempotency_key_abandonedconflict409The prior journal intent was abandoned.
refund_currency_mismatchinvalid_request422Amount 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:

RuleMeaning
next_charge_date_not_laterChoose a date strictly later than the current trial end and next renewal or item period end.
next_charge_date_too_farChoose a date no more than 90 days from now.
subscription_not_reschedulableOnly active or trialing Stripe subscriptions without scheduled cancellation or paused collection can be moved.
subscription_cycle_invoice_pendingA 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

RuleHTTP statusMeaning
recheck_takes_no_values400A re-check accepts only an optional reason, up to 500 characters. Remove all other fields.
recheck_not_available409This 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.

CodeHTTP statusMeaning
receipt_not_available422This payment has no receipt to send. Only succeeded payments linked to a paid invoice have receipts.
receipt_recipient_suppressed422Receipt emails cannot be delivered to this address. Suppressed, bounced and complained addresses cannot receive a resend.
receipt_no_recipient422This customer has no email address to send a receipt to. Add an email address to the customer before retrying.
receipt_resend_too_soon429A 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.

On this page