Skip to main content

Errors

The Proxy API uses conventional HTTP response codes and returns structured error objects to indicate the success or failure of API requests.

Error Response Format

All errors follow this structure:
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key"
  },
  "request_id": "req_abc123def456"
}
FieldDescription
typeThe category of error
codeSpecific error code for programmatic handling
messageHuman-readable description
request_idUnique ID for support requests

Error Types

TypeDescription
authentication_errorInvalid or missing API key
authorization_errorValid auth but insufficient permissions
invalid_request_errorInvalid parameters or malformed request
validation_errorRequest body failed validation
not_found_errorResource doesn’t exist
conflict_errorResource state conflict
rate_limit_errorToo many requests
service_errorInternal or upstream service error

Common Error Codes

Authentication Errors

CodeStatusDescription
missing_api_key401No Api-Key header provided
invalid_api_key401API key is invalid or revoked
expired_api_key401API key has expired

Authorization Errors

CodeStatusDescription
access_denied403No permission to access this resource
insufficient_permissions403Operation requires elevated permissions

Validation Errors

CodeStatusDescription
validation_failed400Request body failed schema validation
parameter_missing400Required parameter not provided
parameter_invalid400Parameter value is invalid
body_parse_error400Request body is not valid JSON

Resource Errors

CodeStatusDescription
not_found404Resource not found
user_not_found404User ID doesn’t exist
agent_not_found404Agent ID doesn’t exist
card_not_found404Card ID doesn’t exist
transaction_not_found404Transaction ID doesn’t exist

Card Errors

CodeStatusDescription
card_not_active400Card must be active for this operation
card_already_closed409Card has already been closed
card_already_frozen409Card is already frozen
agent_suspended400Cannot create cards for suspended agent
max_cards_reached400Agent has reached maximum card limit

Business Logic Errors

CodeStatusDescription
insufficient_funds400User balance too low for this operation
spending_limit_exceeded400Agent or card spending limit reached
kyc_required400User must complete KYC before this operation
kyc_pending400KYC verification in progress
kyc_denied400User KYC was denied
user_not_active400User account is not active
merchant_drift400Transaction merchant differs from card’s first merchant (drift detection)
outside_active_hours400Card can only be used during active hours
cooldown_active400Must wait before next transaction (cooldown policy)
attestation_required400Card requires attestation before credential access
intent_expired400Referenced intent has expired
withdrawal_exceeds_balance400Withdrawal amount exceeds available spending power

Rate Limiting

CodeStatusDescription
rate_limit_exceeded429Too many requests, retry after delay
When rate limited, check the Retry-After header for seconds until you can retry.

HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Access denied
404Not Found - Resource doesn’t exist
409Conflict - Resource state conflict
429Too Many Requests - Rate limited
500Server Error - Internal error
502Bad Gateway - Upstream service error
503Service Unavailable - Temporary outage

Handling Errors

const response = await fetch('https://api.useproxy.ai/v1/agents', {
  headers: { 'Api-Key': apiKey }
});

if (!response.ok) {
  const { error, request_id } = await response.json();

  switch (error.type) {
    case 'authentication_error':
      // Check API key configuration
      break;
    case 'rate_limit_error':
      // Wait and retry
      const retryAfter = response.headers.get('Retry-After');
      await sleep(retryAfter * 1000);
      break;
    case 'validation_error':
      // Fix request parameters
      console.error(error.message);
      break;
    default:
      // Log request_id for support
      console.error(`Error ${error.code}: ${error.message} (${request_id})`);
  }
}

Getting Help

When contacting support, always include:
  1. The request_id from the error response
  2. The endpoint you were calling
  3. The timestamp of the request
This helps us quickly locate and diagnose the issue.