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.

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

Bearer token is missing, expired, or attached to the wrong account context.

Refresh credentials and verify the token 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.

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.

Log response status, response body, endpoint path, and request correlation fields.

Treat 401 and 403 as credential/configuration issues before retrying.

Back off on 429 responses instead of retrying immediately.

Main public endpoint and request/response field reference.

Click, conversion, and postback handling after offer discovery.

Minimal curl walkthrough before production integration.