​
Error Handling

​
Error Response Format

All errors follow a consistent structure: 
{
  "error": {
    "type": "invalid_request",
    "code": "missing_fields",
    "message": "amount is required",
    "requestId": "req_xyz789"
  }
}
Every response includes a requestId for debugging — include it when contacting support.

​
Error Types

TypeHTTP StatusDescription
invalid_request400 / 422Validation error or missing fields
authentication_error401Invalid or missing API key
authorization_error403Valid key but insufficient permissions
not_found404Resource doesn’t exist
conflict409Resource already exists or state conflict
rate_limit429Too many requests
internal_error500Server-side error

​
Validation Errors

Request body validation returns all errors at once (not just the first): 
{
  "error": {
    "type": "invalid_request",
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      { "field": "amount", "message": "\"amount\" is required" },
      { "field": "destination", "message": "\"destination\" is required" }
    ],
    "requestId": "req_xyz789"
  }
}

​
Common Error Codes

CodeDescription
missing_fieldsRequired fields not provided
invalid_chainChain not supported
no_funded_tokenNo token balance found on deposit address
session_expiredSession has expired
session_not_openSession is not in open status
insufficient_balanceVault balance too low
account_not_foundAccount does not exist
deposit_address_not_foundNo deposit address for this account/chain

​
Idempotency

POST endpoints that create resources support the Idempotency-Key header: 
curl -X POST https://api.stableyard.fi/v2/sessions \
  -H "Idempotency-Key: unique-key-123" \
  ...
Sending the same key returns the cached response. Keys are scoped to the partner and expire after 24 hours.