HTTPステータスコード400台エラー時のチェックポイント

freee APIへのリクエストでエラーが発生した際に、以下のようなコードやメッセージを含んだレスポンスが生成されます。

ここでは、HTTPステータスコード40x系のエラーに含まれるメッセージと、解決へのヒントについて記述します。エラーによる分岐を行う際にはメッセージではなく、コードを利用してください。codeは変更が入りませんが、messageには変更がはいる可能性があります。

freee会計 APIのエラーコード

ステータスコード エラーメッセージ エラーコード チェックポイント
401: Unauthorized ログインをして下さい invalid_access_token Access token が有効ではありません。有効なアクセストークンをご利用ください。
アクセスする権限がありません expired_access_token Access token の有効期限切れとなっています。アクセストークンをリフレッシュして下さい。
このAPIにアクセスしたい場合、事業所の管理者にご確認ください。 user_do_not_have_permission リクエストを行なっているユーザーの権限設定で不足しているものがあります。freee の管理画面から 設定>メンバー招待・権限管理>メンバー管理 を選び、正しい権限割り当てができているか確認ください。
存在しないかすでに削除された事業所です。 company_not_found cid(company_id, 事業所ID)の指定が正しいかご確認ください。
有料プランをご利用中の事業所のみご利用いただけます。 freee_plan_limit 利用中のプランをご確認いただき、該当するAPIを利用可能なプランへの変更をご検討お願いします。
接続元のIPアドレスからは、サービスをご利用いただけません。 source_ip_address_limit 事業所のシステム管理者に依頼して、freee APIを利用する拠点のIPアドレスからのアクセス制限を解除して見てください。エンタープライズプランのIP制限機能を利用している場合、freeeの管理画面からIP制限の解除をご検討ください。
アプリのバージョンが更新されてデータアクセス範囲が追加されています。再度認可をしてください。 re_authorization_required

アプリストアで公開をしているアプリに対してScopeの再設定(利用するリソースへの権限を広げる)を伴う改修を行った場合、アプリユーザーは再度OAuthによる認可(アプリが利用するリソースの再確認と承認)を行う必要があります。エラーコードに応じて利用者が再度認可できる体験とするアプリケーションの実装をしてください。

エラーが発生するタイミングはアクセストークンが持つ権限の変更反映についてを参照してください。

指定された認可グラントは不正か、有効期限切れか、無効か、リダイレクトURIが異なるか、もしくは別のクライアントに適用されています。 invalid_grant
  • client_idとclient_secretのパラメーターが正しいかの確認

  • アクセストークンをリフレッシュすると、元のアクセストークンは無効になる。同じアクセストークンを複数回リフレッシュしていないかの確認

  • APIで無効化(revoke)したアクセストークンをリフレッシュしていないかの確認

403: Forbidden このアプリケーションにはアクセス権限がないエンドポイントです。 なし アプリストア>アプリ管理>アプリ詳細>権限設定で以下を確認してください。

データ種別毎の参照、更新を正しく設定する

  • アプリの公開・非公開にかかわらず一つでもチェックが入っていればその設定が適用される

  • アプリが非公開かつなにもチェックがなければすべてチェックが入っているのと同じ権限となる

Response bodyサンプル

以下、エラーコードとメッセージのサンプルです。codeを利用して、メッセージを利用者がアクションをとれるものにカスタマイズしていただけます。

アクセストークンが有効ではない場合

{
    "message": "ログインをして下さい",
    "code": "invalid_access_token"
}

アプリケーション利用者がAPIアクセスに必要な権限を付与されていない場合

{
    "status_code": 401,
    "errors": [
        {
            "type": "status",
            "messages": [
                "アクセス権限がありません。",
                "company_admin",
                "api/v1/approval_requests",
                "index",
                "このAPIにアクセスしたい場合、事業所の管理者にご確認ください。"
            ],
            "codes": [
                "user_do_not_have_permission",
            ],
        }
    ]
}

有料プランのみ利用可能なAPIを利用している場合

{
    "status_code": 401,
    "errors": [
        {
            "type": "status",
            "messages": [
                "有料プランをご利用中の事業所のみご利用いただけます。"
            ],
            "codes": [
                "freee_plan_limit"
            ]
        }
    ]
}

アプリストア掲載アプリが権限を広げてfreeeが承認した場合

{
    "code": "re_authorization_required"
    "message": "アプリのバージョンが更新されてデータアクセス範囲が追加されています。再度認可をしてください。",
}