Errors - Spritz

The Spritz API returns errors as RFC 9457 problem details: a standard, machine-readable JSON shape (served as application/json). Build your error handling against it once and it works across every endpoint.

Problem shape

{
  "type": "urn:problem-type:insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "The wallet has insufficient USDC to cover this off-ramp.",
  "instance": "/v1/off-ramp-quotes"
}

Field	Description
`type`	A `urn:problem-type:` URI identifying the error category. The stable key to branch on.
`title`	Short, human-readable summary of the error category.
`status`	HTTP status code, repeated in the body.
`detail`	Human-readable explanation specific to this occurrence.
`instance`	URI of the specific request that failed.

Some problems include extension members alongside the standard fields for additional context, for example code, realm, scope, resourceType, and resourceId. Treat unknown extension members as optional.

Status codes

Status	Meaning
`400`	Malformed request, such as invalid parameters or body.
`401`	Missing or invalid credentials. See Authentication.
`403`	Authenticated, but not permitted for this resource.
`404`	Resource not found.
`409`	Conflict, such as a duplicate or a state that can’t transition.
`422`	Validation failed on an otherwise well-formed request.
`429`	Rate limited. See Rate Limits.
`5xx`	Something went wrong on Spritz’s side. Safe to retry idempotent requests.

Handling errors

Branch on type (stable) rather than title or detail (human-readable, may change). Surface detail to operators and logs, not directly to end users.

const res = await fetch(url, { headers });

if (!res.ok) {
  const problem = await res.json();
  switch (problem.type) {
    case "urn:problem-type:insufficient-funds":
      // handle the specific case
      break;
    default:
      // log problem.detail and problem.instance for debugging
  }
}