API アクセス時のエラーハンドリングについて

RESTful API では API アクセス時のエラー原因の特定の為にレスポンスコード以外に JSON フォーマットでエラーの内容を返します。

HTTP レスポンスのステータスコードについて

RESTful API では下記の HTTP Status コードを扱っています。

レスポンスコード	レスポンスメッセージ	説明
200	OK	成功
201	Created	新しいリソースの生成が成功しました
202	Accepted	リクエストが正常に受け付けられました
400	Bad Request	リクエストデータに不正値があります
401	Unauthorized	OAuth による認可が失敗しています
404	Not Found	リソースが存在しません
405	Method Not Allowed	メソッドが許可されていません
500	Internal Server Error	API 側の問題による失敗です
503	Service Unavailable	一時的に API アクセスが出来ません

詳しくは OpenSocial RESTful Protocol Specification v0.9 - 13. HTTP Status Codes も参考にして下さい。

エラー時の HTTP レスポンス

エラー時に JSON 形式でエラー内容を返します。各サンプルを参考にして下さい。

TextData API で TextDataGroup コレクションの一覧取得を Proxy モードで行った場合

リクエスト

GET http://sb.app.mbga.jp/api/restful/v1/textdata/@app/@all?format=json
Accept-Encoding: gzip
Authorization: OAuth realm="", oauth_consumer_key="XXXXXXXXXX", oauth_nonce="YYYYYYYY", oauth_signature="ZZZZZZZZZ", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1262688790", oauth_token="AAAAAAAAA", oauth_version="1.0", xoauth_requestor_id="100"
User-Agent: OAuth::Lite::Consumer/1.22

レスポンス

Message の値を見て、この API アクセスでは Proxy モードによるアクセスが出来ないと分かります。

405 Method Not Allowed
Connection: close
Date: Tue, 05 Jan 2010 10:53:10 GMT
Server: lighttpd/1.4.22
Content-Length: 61
Content-Type: application/json
Client-Date: Tue, 05 Jan 2010 10:53:10 GMT

{"Error":{"Message":"Proxy Request is not allowed this API"}}

誤った consumer_key でアクセスした場合

リクエスト

GET http://sb.app.mbga.jp/api/restful/v1/people/@me/@self?format=json
Accept-Encoding: gzip
Authorization: OAuth realm="", oauth_consumer_key="BadConsumerKey", oauth_nonce="XXXXXXX", oauth_signature="YYYYYYYY", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1262689167", oauth_token="ZZZZZZZZZZZ", oauth_version="1.0", xoauth_requestor_id="100"
User-Agent: OAuth::Lite::Consumer/1.22

レスポンス

特定の application の id と consumer_key の対が一致しない場合は下記のようなエラーメッセージが返されます。

401 Unauthorized
Connection: close
Date: Tue, 05 Jan 2010 11:03:58 GMT
Server: lighttpd/1.4.22
Content-Length: 133
Content-Type: application/json
Client-Date: Tue, 05 Jan 2010 11:03:58 GMT

{"Error":{"Message":"wrong consumer infomation ( no exists consumer info [app_id: 12300000, consumer_key: BadConsumerKey] )"}}

注意事項

プログラムのエラーハンドリングには HTTP Status コードのみを利用して下さい。JSON 形式で返されるエラーメッセージは予告無く変更される場合があります。開発時の問題解決の為にご利用下さい。

参考資料

OpenSocial RESTful Protocol Specification v0.9 - 13. HTTP Status Codes

更新履歴

2013/03/15
- ドキュメント移行