# レート制限と規約

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` として渡されます。これにより浮動小数点の丸め誤差を完全に避けられます。表示用の変換は自分のコード側で行ってください。また、各[コレクション](https://getkollek.com/ja/docs/kihon-konseputo/korekushon)は独自の通貨を持つ点にも注意してください。

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

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

:::note
アプリでは見えているオブジェクトに対してエンドポイントが予期せず404を返す場合は、使用しているトークンのユーザーの権限を確認してください。閲覧者のトークンは、すべての書き込み操作に対して404を返します。
:::

## エラーとバリデーション

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

## 次に読むページ

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