Errors & rate limits

Error shape

Every failure returns the same envelope. request_id identifies the exact call — include it when you contact support. details is present on validation failures.

{
  "success": false,
  "request_id": "req_9f2c…",
  "mode": "live",
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "This quote expired. Request a new one.",
    "details": { }
  }
}

Error codes

Idempotency

Send an Idempotency-Key header on mutating endpoints (buy, sell, send, gift and delivery confirms) to make retries safe. Any string up to 100 characters — a UUID is ideal.

Keys are scoped to your partner profile and endpoint and stay valid for at least 24 hours. Reusing one returns the original response with no new side effects, flagged by an idempotent_replay field in the envelope and an Idempotent-Replayed: true response header.

curl -X POST https://api.oropocket.com/partner/buy/confirm \
  -H "Authorization: Bearer oro_live_xxx" \
  -H "Idempotency-Key: 8f14e45f-cea1-4b2c-9d3a-1f2e3d4c5b6a" \
  -d '{"quote_id":"tqt_xxx"}'

Rate limits

The per-minute limits are per IP. The sandbox daily cap is per partner and counts every authenticated request you make in sandbox, whatever the endpoint and whether it succeeds or returns a validation error — so a tight polling loop spends it just as fast as real testing does. Rotating your sandbox token does not reset it.

Sandbox responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds, the next 00:00 IST), so you can see where you stand without waiting to be blocked. Past the cap you get 429 SANDBOX_DAILY_LIMIT with a Retry-After. Your live token keeps working throughout.

If a genuine integration needs more than 1000 sandbox calls a day, ask — the ceiling is configurable per partner.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset — back off when remaining hits zero rather than retrying blindly.