レスポンス & エラー¶

レスポンス¶

すべてのレスポンスは概ね次のようになります:

{
  "meta": {
    "code": 200,
     ...errorType and errorDetail...
  },
  "notifications": {
     ...notifications...
  },
  "response": {
     ...results...
  }
}

errorType はアプリケーション開発者向けの詳細な情報です。以下に示すエラーコードを処理することで、適切なエラーメッセージをユーザに表示左折ことができます。必要に応じて追加の type を追加する場合があります。リクエストが成功した場合でも、非推奨な type が返ってくる場合があります。

meta セクションには、開発者がデバッグする際に役立つ追加情報を提供するメッセージも含まれます。

特定のリクエストには、チェックインやほかのユーザアクションに基づくトップレベルの項目としての通知も含まれます。

JSONP を用いて、リクエストに callback=XXX を追記すると XXX（レスポンス）というレスポンスが返ってきます。 JSONP の場合、つねにステータスコード 200 を返すため（例外的に 500 番台の場合もあります）、ブラウザはコードでレスポンスの処理を行えますが、実際の HTTP ステータスコードは meta レスポンスの code から取得できます。

応答の内容は、API リクエストで渡す m パラメータによって異なる場合があります。詳細な情報は、バージョンと国際化のドキュメントを参照ください。

エラー¶

Foursquare は可能な限り問題の一般的なクラスを示すのに適切な HTTP ステータスコードを使用します。このステータスコードは meta レスポンスの code セクションで繰り返されます。

400 (Bad Request)	パラメータが無効か、必須パラメータが欠けています。OAuth トークンが指定されていない場合やリソース ID が正しく指定されていない場合も該当します。
401 (Unauthorized)	OAuth トークンが無効です。
403 (Forbidden)	リクエストしようとした情報を参照できません。例えば、友達でないユーザに関するすべての情報を参照しようとした場合に発生します。
404 (Not Found)	エンドポイントが存在しません。
405 (Method Not Allowed)	GET のみのエンドポイントで POST しているか、またはその逆の操作を行なっています。
409 (Conflict)	リクエストを完了できませんでした。レスポンスに含まれる情報を使用してリクエストを変更し、再びリクエストを行います。
500 (Internal Server Error)	Foursquare のサーバが不調です。おそらくリクエストは有効ですが、あとで再試行する必要があります。

さらなる詳細は errorType に記述されています。以下のいずれかになります。

`errorType`	ステータスコード	説明
invalid_auth	401	OAuth トークンが提供されていないか無効です。
param_error	400	必要なパラメータが欠けているか不正です。パス内のリソース ID が正しくない場合にも使用されます。
endpoint_error	404	リクエストしようとしたパスが存在しません。
not_authorized	403	認証は成功していますが、プライバシー制限のため情報を見ることを許可されていません。
rate_limit_exceeded	403	時間あたりのレート制限を超えています。
quota_exceeded	429	一日あたりのコールクォータを超えています。
deprecated	200	リクエストに関する何らかの廃止された機能を使用しているか、レスポンスフォーマットが変更されている場合があります。
server_error	場合による	サーバ側で問題が発生しています。status.foursquare.com で状態を確認してみてください。
other	場合による	ほかのエラーが発生しています。

エラーには errorDetail フィールドが含まれ、開発者向けの追加情報が記述されています。場合によってサーバの errorMessage を含む場合があります。これはクライアントがユーザに直接表示するためのローカライズされた文字列です。

参考

Responses & Error (https://developer.foursquare.com/overview/responses)