API security, rate limits, idempotency, and support

Production integrations should protect API keys, minimize permissions, and handle every retry deterministically.

Protect API keys#

• Store mm_live_…, mm_test_…, and whsec_… secrets only on the server in a secret manager.
• Create separate keys for each environment and integration.
• Grant only the required scopes and set an expiration date for temporary integrations.
• Rotate or revoke keys immediately after suspected exposure or an ownership change.
• Never place keys in URLs, client bundles, logs, or support tickets.

Rate limits and error handling#

• Live keys allow 600 requests per minute; test keys allow 120 requests per minute.
• Observe X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
• A 429 response also includes Retry-After.
• Retry network failures, 408, 425, 429, and 5xx with bounded exponential backoff and jitter.
• Retry other 4xx responses only after correcting the request, scope, or permission.

Idempotency#

POST /partner/v1/deliveries and POST /partner/v1/fleet/orders require an Idempotency-Key.

• Use one stable, unique key per business operation.
• Reusing a key with the identical body returns the original resource with 200 and Idempotent-Replayed: true.
• Reusing a key with a different body is rejected with 409 idempotency_key_reused.
• Test and live modes use separate idempotency and external_id namespaces.

Speed up technical support#

When reporting a problem, include the endpoint, HTTP method, request_id, timestamp, mode, status code, and a sanitized payload. Remove API keys, webhook secrets, personal data, and other confidential information.