Errors & Rate Limits

curl -sS https://www.agentspapi.com/api/v1 \
  -H "Authorization: Bearer {{API_KEY}}"

Error Shape

API errors return JSON with a stable envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  },
  "links": {
    "self": { "href": "https://www.agentspapi.com/api/v1/me", "method": "GET" },
    "entrypoint": { "href": "https://www.agentspapi.com/api/v1", "method": "GET" }
  },
  "meta": {
    "request_id": "2d172d8f-...",
    "contract_version": "2026-03-04"
  }
}

error.code is a machine-readable code, error.message is human-readable detail, and meta.request_id should be included when contacting support.

Status Codes

• 200 OK: Request succeeded.
• 400 Bad Request: Query parameter validation failed.
• 401 Unauthorized: Missing or invalid Bearer token.
• 404 Not Found: Requested table or view does not exist.
• 409 Conflict: Data sync is in progress and a queryable snapshot is unavailable.
• 429 Too Many Requests: Per-key rate limit exceeded.

401 Behavior

The API currently returns unauthorized for both missing and invalid tokens.

{
  "error": {
    "code": "unauthorized",
    "message": "Missing bearer token"
  },
  "meta": {
    "request_id": "c62bb4b6-...",
    "contract_version": "2026-03-04"
  }
}

Rate Limits

• Rate limits are applied per API key.
• On 429, read Retry-After for the number of seconds to wait before retrying.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "1707d102-...",
    "contract_version": "2026-03-04"
  }
}

Query Validation Errors

{
  "error": {
    "code": "invalid_query",
    "message": "Unsupported operator 'between' for column 'price'"
  },
  "meta": {
    "request_id": "44f5fdde-...",
    "contract_version": "2026-03-04"
  }
}

Database Syncing

{
  "error": {
    "code": "database_syncing",
    "message": "We are syncing Amazon data to your secure database"
  },
  "meta": {
    "request_id": "debb5d0a-...",
    "contract_version": "2026-03-04"
  }
}