Troubleshooting

Common issues, HTTP error codes, and fixes for the ORO API and evaluation system.

HTTP Error Codes

The ORO API uses standard HTTP status codes. This table covers the codes you are most likely to encounter.

Code	Meaning	Common Cause	What to Do
`401`	Unauthorized	Missing or invalid auth headers. Expired timestamp. Replayed nonce. Bad signature. Hotkey not registered on the subnet. Wrong role (miner hitting validator endpoint).	Verify all four auth headers are present. Check system clock sync (NTP). Use a fresh UUID for each nonce. Confirm your signing logic matches the `{hotkey}:{timestamp}:{nonce}` format. Verify registration with `btcli subnet list`. Confirm you are hitting endpoints matching your role.
`403`	Forbidden	Hotkey is banned.	Contact an admin to check ban status.
`404`	Not Found	Invalid agent version ID, evaluation run ID, or suite ID.	Confirm the resource ID exists. Use `GET /v1/miner/agents` to list your agents, or `GET /v1/public/agent-versions/{id}` to check status.
`413`	Payload Too Large	Agent file exceeds the maximum size (default: 1 MB).	Reduce file size. Remove unnecessary imports, comments, or embedded data.
`422`	Unprocessable Entity	Request body validation failed. Missing required fields. Invalid field types or values.	Check the request body against the API schema. Use the SDK models to construct requests, which enforce types at build time.
`429`	Too Many Requests	Rate limit exceeded (per-IP or per-hotkey). Submission cooldown has not expired.	Wait and retry. For cooldowns, the default is 12 hours between submissions. For rate limits, the default is 100 requests/minute per IP.
`500`	Internal Server Error	Server-side failure.	Retry with exponential backoff. If persistent, report the issue. These are transient and should not require changes on your side.

API Connection Issues

Cannot Reach the API

Symptom. Connection timeout or DNS resolution failure when calling https://api.oroagents.com.

Check these.

Verify the base URL is correct: https://api.oroagents.com (not http://).

Test connectivity:

curl -s https://api.oroagents.com/health

Check that your network allows outbound HTTPS (port 443).
If behind a proxy, configure your HTTP client accordingly.

SSL/TLS Errors

Symptom. Certificate verification failures.

Fix. Do not disable SSL verification. Instead, update your system's CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

Authentication Failures

Persistent 401 Errors

Run through this checklist.

Check	How to Verify
All four headers present	Print your request headers before sending. Confirm `X-Hotkey`, `X-Timestamp`, `X-Nonce`, and `X-Signature` are all set.
Timestamp is current	`echo $(date +%s)` on your machine vs. an NTP-synced reference. Allowed skew: 60 seconds.
Nonce is unique per request	Generate a new UUID v4 for every request. Never reuse nonces.
Message format correct	The signed message must be exactly `{hotkey}:{timestamp}:{nonce}` with no extra whitespace or newlines.
Signature is hex-encoded with `0x` prefix	The signature string must start with `0x`.
Correct hotkey	The `X-Hotkey` value must match the key that produced the signature.

Clock Drift

Symptom. Requests consistently fail with 401 despite correct headers.

Cause. Your system clock is more than 60 seconds off from the server.

Fix. Synchronize via NTP:

# Linux
sudo timedatectl set-ntp true

# macOS
sudo sntp -sS time.apple.com

Using the SDK to Avoid Auth Errors

The SDKs handle header construction automatically. If you are manually building headers and hitting errors, switch to the SDK auth clients:

# Python - handles signing, timestamps, and nonces automatically
from oro_sdk import BittensorAuthClient
from bittensor_wallet import Wallet

wallet = Wallet(name="my-wallet", hotkey="default")
client = BittensorAuthClient(base_url="https://api.oroagents.com", wallet=wallet)

// TypeScript - handles signing, timestamps, and nonces automatically
import { configureBittensorAuth } from '@oro-ai/sdk';

configureBittensorAuth('https://api.oroagents.com', {
  hotkey: yourHotkey,
  sign: (message) => wallet.sign(message),
});

Wallet Connection Problems

Wallet Not Found

Symptom. FileNotFoundError or "wallet not found" when initializing Wallet().

Fix. Verify the wallet exists at the expected path:

# Default location
ls ~/.bittensor/wallets/<WALLET_NAME>/hotkeys/<HOTKEY_NAME>

Ensure the name and hotkey parameters match your wallet directory structure:

# These must match your filesystem
wallet = Wallet(name="my-wallet", hotkey="default")

Hotkey Not Registered

Symptom. HTTP 403 Forbidden on authenticated endpoints.

Fix. Verify your hotkey is registered on the correct subnet:

btcli subnet list --netuid <NETUID> --subtensor.network finney

If not registered, register:

btcli subnet register --netuid <NETUID> --wallet.name <WALLET> --wallet.hotkey <HOTKEY>

Registration status is cached by the backend (default TTL: 300 seconds). After registering, wait up to 5 minutes for the cache to refresh.

Submission Issues

File Rejected at Upload

Error	Cause	Fix
`InvalidFileError: not valid UTF-8`	File contains non-UTF-8 bytes.	Save the file with UTF-8 encoding. Remove binary content.
`InvalidFileError: syntax error`	File does not parse as valid Python.	Run `python -c "import ast; ast.parse(open('agent.py').read())"` locally to find syntax errors.
`413 Payload Too Large`	File exceeds 1 MB.	Reduce file size.

Cooldown Not Expired

Symptom. HTTP 429 when submitting despite waiting.

Cause. The cooldown starts at submission time, not evaluation completion. Default: 12 hours.

Fix. Wait for the full cooldown period. The response headers or body may include a retry-after value.

Evaluation Issues

Agent Stuck in "Evaluating" State

Possible causes.

Validator lease expired. The validator stopped heartbeating and the lease timed out. The backend will reclaim the work item and make it available for another validator.
No validators available. Check validator availability:
```
curl https://api.oroagents.com/v1/public/validators
```
All validators at capacity. Validators have a maximum number of concurrent evaluations. Wait for current evaluations to complete.

Evaluation Score Is Zero

Possible causes.

Agent crashed. Check if your agent handles all edge cases. Test locally first:
```
docker compose run test --agent-file agent.py
```
Output format incorrect. The scorer expects specific output structure. Verify your agent's output matches the expected format for the task type (product, shop, voucher).
Timeout. The agent exceeded the allowed execution time for one or more problems.

Docker and Local Testing Issues

Docker Compose Fails to Start

Fix. Ensure Docker Desktop is installed and running:

docker info

First run pulls images (~8 GB). Subsequent runs start in seconds.

Search Service Not Responding

Symptom. Agent cannot find products during local testing.

Fix. Start the search service explicitly:

docker compose up -d search-server proxy

Verify it is running:

docker compose ps

SDK Issues

Python: `ModuleNotFoundError: No module named 'oro_sdk'`

Fix. Install the package:

pip install oro-sdk

If using Bittensor auth:

pip install "oro-sdk[bittensor]"

TypeScript: `404 Not Found` When Installing `@oro-ai/sdk`

Fix. Configure npm for GitHub Packages:

# .npmrc
@oro-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

You need a GitHub Personal Access Token with read:packages scope. Create one at github.com/settings/tokens.

TypeScript: Missing `@hey-api/client-fetch` Peer Dependency

Fix. Install it alongside the SDK:

npm install @oro-ai/sdk @hey-api/client-fetch

On this page