HTTP API

This page summarizes the common HTTP behavior shared by Streaming API endpoints.

Rate limits

Endpoints are classified into tiers based on computational complexity and usage frequency.

Tier	Description	RPS
Tier 1 — Critical	High-frequency, critical actions	60
Tier 2 — Moderate	Moderate-frequency, supplementary actions	25
Tier 3 — Low	Low-frequency, operational management	10

When a limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header.

Status	Meaning
`200`	Request completed. Some business-level responses still need body inspection.
`4xx`	Request or authentication issue. Check the response body for detail.
`5xx`	Server-side error. Retry with backoff and report if persistent.

Most non-authentication errors use this format:

{
  "error": "human readable error message",
  "code": "machine_friendly_error"
}

Authentication errors use:

{
  "message": "Forbidden"
}

Code	Meaning
`*_not_found`	Resource cannot be found, for example `customer_not_found`.
`forbidden_request`	Resource is forbidden for this request.
`invalid_request`	Request is missing a required parameter or uses an invalid value.
`server_error`	Server error.
`customer_not_enough_score`	Customer does not have enough balance for the operation.
`customer_inactive`	Customer is inactive, so the operation cannot be executed.
`voucher_redeemed`	Voucher is already redeemed.
`voucher_expired`	Voucher is expired.
`voucher_inactive`	Coupon/Voucher is inactive.
`voucher_deleted`	Coupon was deleted.
`voucher_out_location`	Voucher cannot be redeemed in the current location.
`voucher_out_date`	Voucher is not yet available.
`voucher_not_found`	Voucher was not found, Customer was not found, or Voucher does not belong to the Customer.
`exchange_not_found`	Score exchange is not found for the requested location.

For server_error or unexpected errors, retry with exponential backoff: start at 1 second and increase up to 32 seconds.

Type	Format
Integer	`123`
Float	`123.45` with dot decimal separator
String	`hello`
Date	`2016-12-31`
DateTime	`2016-12-31T23:59:43Z`
Boolean	`true` or `false`
Array	`[{"key": "value"}]`
Slug	Short label with letters, numbers, underscores, or hyphens

Dates and DateTimes must use ISO-8601 in UTC whenever possible.

X-Api-Key: <api-key>
X-Api-Secret: <api-secret>
X-Api-Version: 1

For companies with multilanguage enabled, send Accept-Language to request translatable content in a specific language:

Accept-Language: en

If the language is not available, the API returns the Company's default language.

Use Idempotency-Key for retryable POST, PATCH, and PUT requests that must not be processed twice.

Idempotency-Key: QknyRdIN6wECfOb5

Do not send idempotency keys on GET or DELETE requests.

Keys expire after 24 hours and cannot be reused with different request parameters.

Some endpoints can register the author of the request through an email header. The current source documentation calls out: