REST 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.sp.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.sp.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/01
    • ドキュメント移行

PREVIOUS

会員区分(Grade)について

NEXT

リクエストに関するパフォーマンスガイドライン