# Management API best practices

> Use these best practices to build a reliable and efficient integration with the Talon.One Management API.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

## Rate limits

The Management API allows up to three requests per second per endpoint.

- **Keep all Management API calls out of user-facing flows.** Reserve it for back-office
  operations: reporting pipelines, coupon generation for support agents, scheduled data
  imports. Never call Management API endpoints from checkout or other real-time paths.
- **Stay comfortably under the limit.** Design automations to run at two requests per
  second or fewer to leave headroom.
- **Handle 429 responses.** If you receive a `429 Too Many Requests`, wait before
  retrying. Use exponential backoff with jitter: randomize the delay to avoid synchronized
  retry waves.
- **Notify Talon.One before bulk operations.** If you plan a large data migration, mass
  import, or when you have a large sales event approaching, contact
  [support@talon.one](mailto:support@talon.one) at least five business days in advance so
  the infrastructure can be prepared. This also applies after the initial integration
  phase.

## Avoid immediate reads after writes

After updating a customer session, tracking an event, or updating a customer profile,
avoid immediately calling endpoints that read the updated data. Some endpoints read from
replica databases, which can take a short time to reflect recent writes. Wait for the
write request to complete, then wait up to 1 second before making a read request. If the
response still reflects the previous state, retry with backoff.

## API key management

Management API keys are tied to the user account that created them. If that user is
deactivated through manual offboarding or an SSO or IdP change, all their keys stop
working immediately, breaking any automation that depends on them.

- **Use a dedicated account for automation keys.** Create a non-personal user (a bot or
  service account) and use it to create all Management API keys used by automated systems.
  This decouples key validity from individual staff lifecycles.
- **Set an expiration date** when creating every key.
- **Rotate keys on a schedule** aligned with your InfoSec policy.
- **Store keys immediately on creation.** A key is shown only once: if you lose it, you
  must create a new one.
- **Never embed keys in client-side code.** Always call the Management API from a backend
  environment.

See [Manage Management API keys](/docs/product/account/dev-tools/manage-mapi-keys.md).

## Large data operations

Management API endpoints for imports and exports can handle large datasets. Apply these
practices to keep operations efficient and predictable.

- **Use pagination for large result sets.** Pass the `pageSize` and `skip` parameters to
  page through results. Avoid fetching all records in a single call.
- **Use batch endpoints where available.** Endpoints such as
  [Create loyalty cards](/management-api#tag/Loyalty/operation/createBatchLoyaltyCards),
  [Create coupons asynchronously](/management-api#tag/Coupons/operation/createCouponsAsync)
  and
  [Create coupon deletion job](/management-api#tag/Coupons/operation/createCouponsDeletionJob)
  are more efficient than making one request per record.
- **Schedule long-running operations off-peak.** Imports and exports are excluded from the
  standard 5-minute timeout cap but still consume backend resources. Run them during
  low-traffic periods to avoid contention with Integration API traffic.

## Health monitoring

Use the
[Application API health endpoint](/management-api#tag/Applications/operation/getApplicationApiHealth)
to monitor the health of your API connection in steady state.

| Status | Meaning |
|--------|---------|
| `OK` | Only successful requests in the last 5 minutes. |
| `WARNING` | At least one failed request in the last 5 minutes. |
| `ERROR` | More than 50% of requests failed. |
| `CRITICAL` | All requests failed. |
| `NONE` | No Integration API requests recorded in the last 5 minutes. |

This endpoint reflects Integration API traffic only, not Management API traffic. Use it
for steady-state monitoring while your integration is active. Do not use it to decide when
to restore traffic after an outage: while the circuit breaker is open and no requests are
flowing, the status returns `NONE`, which cannot confirm recovery.

## Related pages

- [Management API overview](/docs/dev/management-api/overview.md)
- [Manage Management API keys](/docs/product/account/dev-tools/manage-mapi-keys.md)
- [Integration API best practices](/docs/dev/integration-api/best-practices.md)