レート制限と規約

API全体に適用される、いくつかの共通の規約があります。一度覚えておけば、どのエンドポイントを使うときも驚かずに済むため、リファレンスの中で繰り返す代わりにこのページにまとめています。

レート制限

• 認証済みのリクエストは、ユーザーごとに1分あたり60回に制限されます。
• POST /api/register と POST /api/login は1分あたり6回に制限され、クレデンシャルスタッフィング攻撃を防ぎます。

制限を超えると、APIはHTTP 429を返します。少し待ってから再試行してください。一括インポートを書く場合は、できるだけ速く送るのではなく、リクエストの間隔を調整してください。また、バルク用のエンドポイントは存在しないため、APIは1リクエストにつき1オブジェクトを処理する仕組みになっている点も覚えておいてください。

ページネーション

一覧を返すエンドポイントはページネーションされ、共通のエンベロープを共有します。

• data: そのページに含まれるリソース。
• links: first、last、prev、next のURL。
• meta: 現在のページ、総件数などの関連情報。

1ページにはデフォルトで10件のリソースが含まれます。per_page クエリパラメータで件数を増やせますが、最大100件までです。links.next が null になるまでたどれば、一覧全体を走査できます。

金額は最小通貨単位で表されます

APIに登場するすべての金額(推定価値、取引金額、預り金、被保険価値)は、その通貨の最小単位を表す整数です。ドルやユーロであればセント単位になり、49.99ドルの購入は 4999 として渡されます。これにより浮動小数点の丸め誤差を完全に避けられます。表示用の変換は自分のコード側で行ってください。また、各コレクションは独自の通貨を持つ点にも注意してください。

権限がない場合は「見つからない」扱いになります

APIは、Webアプリと同じ権限を適用しますが、1つ意図的な違いがあります。実行を許可されていない操作や、他のアカウントのリソースに対する操作は、403 Forbiddenではなく404 Not Foundを返します。呼び出し側からは「存在しない」のか「自分のものではない」のかを区別できず、APIは自分のアカウント外に何が存在するかを一切明かしません。

エラーとバリデーション

バリデーションに失敗すると、HTTP 422とともに message と、フィールド名をキーとする errors オブジェクトが返されます。それ以外のエラーは通常のHTTPの意味に従います。トークンがない、または失効している場合は401、404は前述のとおり、レート制限には429です。

次に読むページ

• これらの規約が実際のエンドポイントでどう適用されているかは、/docs/api の自動生成リファレンスで確認できます。
• 将来のイベント配信に備えたいですか。Webhook で現時点の状況を確認してください。