Skip to content
AON - Agent Offer Network

API Reference

Errors & Rate Limits

Understand common API failures, retry boundaries, and the endpoints most likely to surface integration issues.

Contract model

HTTP status

400, 401, and 429 are transport-layer status values returned as the HTTP response status. They are not fields in the JSON body.

JSON body envelope
{ code, message, data, extra }

Branch on response.status first, then use body.code and body.message for product-level handling and support logs.

Common errors

400

Request body is missing required fields or uses an unsupported shape.

Compare the request body table and example for the endpoint before retrying.

401

On Offer Query, no placement id was sent and anonymous mode is unavailable (or a non-sandbox `aon_test_` key was sent without a placement). On account routes, the bearer token is missing, expired, or attached to the wrong account context.

Send your placement id on Offer Query (without one, Offer Query runs in anonymous mode when available). On account routes, refresh the token and verify it with `GET /v1/auth/me`.

429

The integration is sending too many requests in a short window.

Apply exponential backoff, add jitter, and avoid immediate retry loops.

Rate limit handling

  • Use retry_after_seconds from extra when it is present.
  • Add exponential backoff with jitter before retrying 429 responses.
  • Avoid retrying 400 request-shape errors until the payload is fixed.
  • Treat 401/403 as credential or environment configuration issues before retrying.

Troubleshooting checklist

Log response status, response body, endpoint path, and request correlation fields.
Treat 401 and 403 as identity or configuration issues before retrying.
Back off on 429 responses instead of retrying immediately.
Offer Query

Main public endpoint and request/response field reference.

Tracking

Click, conversion, and postback handling after offer discovery.

First API Call

Minimal curl walkthrough before production integration.