Status Codes & Error Handling

This section describes HTTP status codes, a standard error schema, and endpoint-specific conditions for the Conversion API.

Error Object (standard)

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "The quote has expired. Please request a new quote.",
    "details": {
      "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3",
      "valid_until": "2025-08-21T07:56:57.981Z",
      "reason": "TTL_EXPIRED"
    },
    "request_id": "req_01hx9p0v2d0c6n3",
    "timestamp": "2025-08-21T07:57:00.001Z"
  }
}

Common HTTP Statuses

HTTP	Meaning	When it happens	Client action
200	OK	Successful GET (e.g., Retrieve Hedge)	Proceed
201	Created	Successful POST (e.g., Create Hedge)	Store identifiers
202	Accepted	Request accepted for processing (async hedging)	Poll status
400	Bad Request	Missing/invalid fields, bad enum, malformed amount	Fix payload and retry
401	Unauthorized	Missing/invalid token, signature	Refresh/attach auth
403	Forbidden	Portfolio not permitted, scope missing	Adjust scopes/permissions
404	Not Found	Portfolio/quote/hedge not found	Verify IDs
409	Conflict	Quote expired, already hedged, duplicate action	Re-quote or use idempotency
422	Unprocessable Entity	Amount out of bounds, unsupported pair/network	Correct business inputs
429	Too Many Requests	Rate limit exceeded	Backoff and retry
500	Internal Server Error	Unexpected server fault	Retry with backoff
503	Service Unavailable	Dependency/venue down, maintenance	Retry later with backoff

Error Codes (enumeration)

error.code	Typical HTTP	Description
`VALIDATION_ERROR`	400/422	Generic validation failure (schema/enum/format)
`MISSING_FIELD`	400	Required field absent (e.g., from_asset.asset)
`INVALID_AMOUNT`	422	Amount is non-numeric, negative, or exceeds limits
`UNSUPPORTED_ASSET`	422	Asset not supported by portfolio or venue
`UNSUPPORTED_NETWORK`	422	Network not supported for given asset
`PORTFOLIO_NOT_FOUND`	404	Portfolio ID invalid or inaccessible
`QUOTE_NOT_FOUND`	404	`quote_id` not found
`QUOTE_EXPIRED`	409	`valid_until` has passed
`QUOTE_ALREADY_HEDGED`	409	Hedge already created for this `quote_id`
`HEDGE_NOT_FOUND`	404	Hedge not found for given identifiers
`INSUFFICIENT_LIQUIDITY`	422	Unable to price/execute requested size
`RISK_LIMIT_EXCEEDED`	403/422	Portfolio or product risk limit hit
`AUTHENTICATION_FAILED`	401	Invalid credentials/signature
`AUTHORIZATION_FAILED`	403	Token lacks required scopes/role
`RATE_LIMITED`	429	Too many requests
`VENUE_UNAVAILABLE`	503	External market/custody dependency down
`INTERNAL_ERROR`	500	Unexpected server error

Create Quote — Status & Errors

Endpoint: POST /v1/portfolios/{portfolio_id}/conversions/quote

HTTP	Example `error.code`	When
200	—	Quote priced successfully
400	`MISSING_FIELD`, `VALIDATION_ERROR`	from_asset/to_asset shape invalid; both amounts supplied or none supplied
401	`AUTHENTICATION_FAILED`	Token missing/invalid
403	`AUTHORIZATION_FAILED`, `RISK_LIMIT_EXCEEDED`	Scope missing; product/risk guardrail
404	`PORTFOLIO_NOT_FOUND`	Portfolio invalid/inaccessible
422	`UNSUPPORTED_ASSET`, `UNSUPPORTED_NETWORK`, `INVALID_AMOUNT`, `INSUFFICIENT_LIQUIDITY`	Business constraints
429	`RATE_LIMITED`	Rate cap hit
500/503	`INTERNAL_ERROR`, `VENUE_UNAVAILABLE`	Temporary fault

Sample 422 (unsupported pair)

{
  "error": {
    "code": "UNSUPPORTED_ASSET",
    "message": "Asset pair USD→XYZ is not supported for this portfolio.",
    "details": { "from_asset": "USD", "to_asset": "XYZ" },
    "request_id": "req_...",
    "timestamp": "2025-08-21T07:56:58Z"
  }
}

Create Hedge — Status & Errors

Endpoint: POST /v1/portfolios/{portfolio_id}/conversions/hedge

HTTP	Example `error.code`	When
201	—	Hedge created (synchronous)
202	—	Hedge accepted (asynchronous execution)
400	`VALIDATION_ERROR`	Payload not valid JSON or schema
401	`AUTHENTICATION_FAILED`	Token invalid/missing
403	`AUTHORIZATION_FAILED`, `RISK_LIMIT_EXCEEDED`	Scope/limit issues
404	`QUOTE_NOT_FOUND`	`quote_id` unknown
409	`QUOTE_EXPIRED`, `QUOTE_ALREADY_HEDGED`	TTL passed or duplicate hedge
422	`UNSUPPORTED_ASSET`, `UNSUPPORTED_NETWORK`, `INSUFFICIENT_LIQUIDITY`	Execution constraints
429	`RATE_LIMITED`	Rate cap hit
500/503	`INTERNAL_ERROR`, `VENUE_UNAVAILABLE`	Temporary fault

Sample 409 (expired)

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "The quote has expired. Please request a new quote.",
    "details": { "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3", "valid_until": "2025-08-21T07:56:57.981Z" },
    "request_id": "req_...",
    "timestamp": "2025-08-21T08:00:02Z"
  }
}

Retrieve Hedge — Status & Errors

Endpoint: GET /v1/portfolios/{portfolio_id}/conversions/hedge

HTTP	Example `error.code`	When
200	—	Hedge details returned
400	`VALIDATION_ERROR`	Bad query param (e.g., malformed conversion_id)
401	`AUTHENTICATION_FAILED`	Token invalid/missing
403	`AUTHORIZATION_FAILED`	No access to portfolio/hedge
404	`HEDGE_NOT_FOUND`	No hedge matches the provided identifiers
429	`RATE_LIMITED`	Rate cap hit
500/503	`INTERNAL_ERROR`, `VENUE_UNAVAILABLE`	Temporary fault

Sample 404

{
  "error": {
    "code": "HEDGE_NOT_FOUND",
    "message": "No hedge found for the specified conversion_id.",
    "details": { "conversion_id": "conv-uuid" },
    "request_id": "req_...",
    "timestamp": "2025-08-21T08:06:01Z"
  }
}

Idempotency, Retries & Rate Limits

Topic	Guidance
Idempotency	For POSTs (`/conversions/hedge`), send `Idempotency-Key` (v4 UUID). Reusing the same key within 24h yields the original result or a 409 if the parameters differ.
Retries (client)	Retry GET on 500/503/429 with exponential backoff (e.g., 200ms → 400ms → 800ms, jitter). For POST hedge, rely on idempotency rather than blind retries.
Retry-After	On 429/503, honor `Retry-After` (seconds).
Time bounds	Quotes are valid until `valid_until` (ISO-8601). Re-price after expiry.
Request IDs	Log `request_id` from error responses for support correlation.

Security & Permissions (quick reference)

Requirement	Notes
Auth	Bearer token with portfolio-scoped permissions.
Scopes	`conversions:quote:create`, `conversions:hedge:create`, `conversions:hedge:read` (example naming).
Clock skew	Keep client clock in sync (NTP). Quote TTL is time-sensitive.