Errors

Errors use a stable machine-readable code with a human-readable message. Wallets should provide a useful recovery action rather than treating every error as a generic failure.

Example

{
  "error": {
    "code": "IDENTIFIER_UPDATE_PENDING",
    "message": "Payment destination update is still in its safety period."
  }
}

Common codes

• IDENTIFIER_NOT_FOUND, IDENTIFIER_INVALID
• IDENTIFIER_PENDING, IDENTIFIER_UPDATE_PENDING
• IDENTIFIER_SUSPENDED, IDENTIFIER_REMOVED
• TYPE_NOT_SUPPORTED, DESTINATION_UNAVAILABLE
• PROVIDER_NOT_APPROVED, UNAUTHORIZED, FORBIDDEN
• RATE_LIMITED and FREE_API_RATE_LIMITED

HTTP 401 and 403 indicate an authentication or authorization problem; HTTP 429 indicates retryable rate limiting. Preserve the error code in logs and client telemetry.

Client recovery

if (response.status === 429) {
  const seconds = Number(response.headers.get("Retry-After") ?? 60);
  scheduleRetry(seconds);
} else if (response.status === 401) {
  requestNewCredential();
} else if (response.status === 404) {
  showIdentifierNotFound();
} else {
  showResolverError();
}

Never retry invalid input, revoked identifiers, or authorization errors indefinitely. Preserve the machine-readable error.code for telemetry and user-facing recovery.