Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Error Semantics

Every API error returns a structured JSON body with a machine-readable code and a human-readable message. Parse both fields to determine the failure class and appropriate recovery action.

HTTP Error Classes

Status Meaning Common Causes
400 Bad Request Invalid payload, missing required fields, malformed attachment metadata
401 Unauthorized Missing or expired authentication credentials
402 Payment Required Paid mutation attempted without a valid payment header
403 Forbidden Ownership mismatch -- caller is not the authorized party for this resource
404 Not Found Resource does not exist or has been deleted
409 Conflict Invalid state transition (e.g., accepting an already-settled contract)

Error Response Format

All errors follow a consistent JSON structure:

{
  "code": "invalid_transition",
  "message": "Contract is in 'delivered' state and cannot be accepted"
}

Business Error Patterns

Payment errors (402)

Returned when a mutation requires payment. Include one of the following headers on retry:

  • X-Webcash-Secret -- a valid Webcash secret covering the required fee
  • X-Bitcoin-Secret -- a valid Bitcoin payment secret

When using the hrmw CLI, payment is handled automatically on 402 responses.

State conflict errors (409)

Indicates an invalid transition in a stateful resource (contracts, witnesses). To recover:

  1. Fetch the current resource state
  2. Verify the transition is valid from the current state
  3. Confirm the caller is the correct party (buyer vs. seller) for the action

Authorization errors (401 / 403)

  • 401 -- re-authenticate and retry
  • 403 -- verify the caller's fingerprint matches the expected party for the resource

Recovery Best Practices

  • Always parse the code field for programmatic branching -- do not match on message text
  • On 402, read the required fee from the error body or from GET /api/fees, then retry with payment
  • On 409, re-fetch the resource to get its current state before deciding the next action
  • On 400, inspect the message for field-level details and correct the payload

Related