Errors#

Errors return a non-2xx status with a JSON body containing a human-readable error and a stable machine-readable code. Validation failures add a details object keyed by field.

{
  "error": "Validation failed.",
  "code": "VALIDATION_ERROR",
  "details": {
    "cover_amount": ["The cover amount may not be greater than 15000."]
  }
}

Always branch on code, never on the error text - the wording may change, the codes will not.

Status codes#

Status	Meaning
200	Success.
201	Resource created (sessions, agreements, invoices).
400	The request is understood but not allowed in the current state.
401	Missing or invalid API key.
403	Gateway not enabled for the entity.
404	Resource not found, or not owned by your entity.
422	Validation failed.
429	Rate limit exceeded.
500	Unexpected server error.

Common codes#

Code	Status	Meaning
`VALIDATION_ERROR`	422	One or more fields failed validation. See `details`.
`SESSION_NOT_FOUND`	404	No session with that ID for your entity.
`SESSION_CREATION_FAILED`	500	Session could not be created.
`AGREEMENT_NOT_FOUND`	404	No agreement with that ID for your entity.
`AGREEMENT_NOT_ACTIVE`	400	Agreement exists but is not `active`.
`AGREEMENT_NO_TENANT`	400	Agreement has no tenant attached.
`AGREEMENT_CREATION_FAILED`	500	Agreement could not be created.
`CANCEL_FAILED`	400	Session cannot be cancelled - already terminal, or already paid.
`INVALID_API_KEY`	401	Key not recognised or revoked.
`GATEWAY_NOT_ENABLED`	403	Gateway disabled for the entity.

Business-rule errors#

Some 4xx responses reject an otherwise well-formed request because of a domain rule:

Message	Rule
`deposit_mode is required when cover_amount is greater than 0.`	A guarantee needs an explicit deposit decision.
`payment_link agreements cannot have cover_amount.`	Payment links carry no guarantee.
`Either amount, cover_amount, or first_payment_amount is required.`	A session must charge something.
`Session payment has already completed and cannot be cancelled.`	Paid sessions are immutable.

See Amounts and pricing for the full set of amount rules.