Errors and Rate Limits

The Oris API uses standard HTTP status codes and returns structured error responses. The SDKs map these to typed exception classes for language-idiomatic error handling.

Error Response Format

Every error response follows a consistent JSON structure. The code field is a machine-readable identifier. The message field is a human-readable description. The details field provides additional context when available.

Error Response

{
  "error": {
    "code": "POLICY_VIOLATED",
    "message": "Payment rejected by spending policy.",
    "request_id": "req_8f3a2b1c-d4e5-6789-abcd-ef0123456789",
    "details": {
      "violated_rules": ["max_per_transaction", "max_daily"],
      "action": "reject"
    }
  }
}
  

Error Codes

HTTP	Code	Description
400	`BAD_REQUEST`	Malformed request body or missing required fields
401	`UNAUTHORIZED`	Invalid API key, HMAC signature, timestamp, or nonce
402	`WALLET_INSUFFICIENT_BALANCE`	Wallet balance too low for this transaction
403	`FORBIDDEN`	Developer KYB not verified or insufficient permissions
403	`POLICY_VIOLATED`	Payment rejected by one or more spending policies
403	`PAYMENT_COMPLIANCE_BLOCKED`	Payment blocked by Veris compliance pre-screen
403	`PAYMENT_REJECTED`	Payment rejected during processing
404	`RESOURCE_NOT_FOUND`	Requested agent, wallet, payment, or policy does not exist
404	`WALLET_NOT_FOUND`	No wallet found for the specified agent and chain
409	`WALLET_FROZEN`	Wallet is frozen pending compliance review
422	`VALIDATION_ERROR`	Request body fails schema validation
429	`RATE_LIMITED`	Too many requests. Respect the `Retry-After` header.
202	`PAYMENT_ESCALATED`	Payment requires human approval per escalation policy
502	`UPSTREAM_ERROR`	Blockchain RPC or external service failure
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable
504	`GATEWAY_TIMEOUT`	Upstream request timed out

SDK Error Hierarchy

Both the Python and TypeScript SDKs map HTTP errors to a typed exception hierarchy. This lets you catch specific error categories without inspecting status codes.

Error Hierarchy

OrisError                      # Base class (all errors)
  OrisAuthError                # 401, 403 (auth/permission)
  OrisRateLimitError           # 429 (includes retryAfter)
  OrisValidationError          # 400, 422 (bad input)
  OrisPaymentError             # Payment-specific failures
  OrisNetworkError             # Connection, timeout, DNS
  

Every error instance exposes these properties:

Property	Type	Description
`message`	string	Human-readable error description
`statusCode`	number	HTTP status code
`errorCode`	string	Machine-readable error code (e.g., `POLICY_VIOLATED`)
`requestId`	string	Unique request identifier for support debugging
`details`	object	Additional context (violated rules, amounts, etc.)

TypeScript Error Handling

error-handling.ts

import {
  OrisError,
  OrisAuthError,
  OrisRateLimitError,
  OrisPaymentError,
  OrisValidationError,
  OrisNetworkError
} from '@oris/sdk'

try {
  const payment = await agent.pay({ to: '0x...', amount: 100 })
} catch (err) {
  if (err instanceof OrisRateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`)
  } else if (err instanceof OrisPaymentError) {
    console.log(`Payment failed: ${err.errorCode}`, err.details)
  } else if (err instanceof OrisAuthError) {
    console.log('Check your API key and secret')
  } else if (err instanceof OrisValidationError) {
    console.log(`Invalid request: ${err.message}`)
  } else if (err instanceof OrisNetworkError) {
    console.log('Network issue, will retry automatically')
  }
}
  

Python Error Handling

error_handling.py

from oris.errors import (
    OrisError, OrisAuthError, OrisRateLimitError,
    OrisPaymentError, OrisValidationError, OrisNetworkError
)

try:
    payment = agent.pay(to="0x...", amount=100)
except OrisRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except OrisPaymentError as e:
    print(f"Payment failed: {e.error_code}", e.details)
except OrisAuthError:
    print("Check your API key and secret")
except OrisError as e:
    print(f"Unexpected error: {e}")
  

Rate Limits

Rate limits are enforced per developer using a Lua token bucket in Redis. The limit applies per second, derived from the per-minute allocation for your plan.

Plan	Requests/min	Agents	Transactions/mo
Free	60	3	500
Growth	300	25	10,000
Scale	1,000	200	100,000
Enterprise	Custom	Unlimited	Unlimited

Rate Limit Headers

Every response includes rate limit information in the headers.

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Seconds until the window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

Retry Strategy

The SDKs implement automatic retries with exponential backoff and jitter for retryable errors (429, 502, 503, 504). The default configuration retries up to 3 times with a maximum backoff of 30 seconds.

Parameter	Default	Description
Max retries	3	Maximum number of retry attempts
Base delay	500ms	Initial backoff delay
Max backoff	30,000ms	Maximum delay between retries
Jitter	0-500ms	Random jitter added to each delay
429 handling	Respect Retry-After	Uses the server-provided delay for rate limit errors

Backoff Formula

delay = min(500 * 2^attempt, 30000) + random(0, 500)

# Attempt 0: 500-1000ms
# Attempt 1: 1000-1500ms
# Attempt 2: 2000-2500ms
# Attempt 3: 4000-4500ms
  

Non-Retryable Errors

The following status codes are never retried because they indicate a problem with the request itself:

Status	Reason
400	Request is malformed. Fix the payload before retrying.
401	Authentication failed. Check credentials.
403	Permission denied or policy violation. Will not change on retry.
404	Resource does not exist.
409	Conflict state (e.g., wallet frozen). Resolve the conflict first.
422	Validation error. Fix the request body.

Idempotency. POST and PATCH requests include an Idempotency-Key header. If a retry sends the same key, the server returns the original response instead of executing the operation again. This prevents duplicate payments on network failures.