Skip to main content

​
Error Code Reference

CodeHTTPDescription
INVALID_SIGNATURE401Signature verification failed
TIMESTAMP_EXPIRED401Timestamp outside ±5 minute window
NONCE_REUSED401Nonce already seen (replay attempt)
UNKNOWN_OCID401OCID not found in registry
METADATA_UNAVAILABLE502Could not fetch sender’s metadata
INVALID_PROOF400Proof structure is malformed
PROOF_SIGNATURE_INVALID400Proof signature verification failed
ISSUER_NOT_ACCEPTED400Proof issuer not in settlement.accepts
AMOUNT_MISMATCH400Proof amount doesn’t match transaction
CURRENCY_MISMATCH400Proof currency doesn’t match transaction
TXID_NOT_FOUND404Referenced transaction doesn’t exist
TRANSACTION_EXPIRED410Settlement window has closed
INSUFFICIENT_FUNDS402Sender has insufficient balance
CAPABILITY_NOT_SUPPORTED400Service doesn’t support requested operation
RATE_LIMITED429Too many requests

​
Connection Refused (403)

Services may refuse connections at their discretion without providing a specific reason. This is distinct from authentication failures (401) or validation errors (400). A 403 response during handshake means the service has chosen not to establish a connection. The response body is optional and may be empty. 
{
  "error": {
    "code": "CONNECTION_REFUSED",
    "message": "Connection not accepted"
  }
}
Common reasons a service might refuse a connection include:
  • Business policy decisions
  • Compliance or regulatory requirements
  • Geographic restrictions
  • Internal blocklists
Services are not required to disclose why a connection was refused.

​
Handling refused connections

  • Do not retry immediately — the refusal is intentional
  • Check your metadata is correctly published and discoverable
  • Contact the service operator through out-of-band channels if you believe the refusal is in error

​
Error Response Format

{
  "error": {
    "code": "ISSUER_NOT_ACCEPTED",
    "message": "Proof issuer OCID 999 is not in accepted settlement sources",
    "details": {
      "providedIssuer": 999,
      "acceptedIssuers": [100, 101, 102]
    }
  }
}