DocsReference
Error Codes
All Aidress API errors return JSON with a detail field explaining what went wrong.
json
{
"detail": "Agent 'agent_ghost_00' not found in registry."
}HTTP status codes
| Code | Name | When it happens |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Agent or key successfully created |
| 202 | Accepted | Registration paused — capability confirmation required |
| 400 | Bad Request | Malformed request body |
| 403 | Forbidden | Anti-gaming rule fired, or invalid admin key |
| 404 | Not Found | Agent ID does not exist |
| 409 | Conflict | agent_id or org_domain already registered |
| 422 | Unprocessable | Validation error — field format, missing required field |
| 503 | Unavailable | Service temporarily unavailable. Retry with backoff. |
Handling 503
If the API returns 503, retry with backoff. The Python SDK handles this automatically (7 retries, 5s interval). For raw HTTP clients:
python
import time, requests
for attempt in range(7):
res = requests.post("https://api.aidress.ai/verify", json={"agent_id": "..."})
if res.status_code != 503:
break
time.sleep(5)Anti-gaming 403s
When a /review is blocked, the detail field tells you which rule fired:
| Detail message | Rule |
|---|---|
"Rater trust score too low." | Rater must have score >= 50 |
"Rater and receiver share the same org domain." | No same-org ratings |
"Transaction already rated." | One rating per transaction_id |
"Cannot rate yourself." | Self-rating blocked |
"Org rating cap reached." | 20% per-org-domain cap exceeded |
"Rater influence cap reached." | 10% per-individual cap exceeded (unaffiliated rater) |