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 |
| |
| 現在ご契約中のプランではこのプラン限定アプリを利用できません。 | not_available_plan_limited_app | 事業所のプランがご利用アプリの利用可能プランに該当するかご確認ください。 | |
| 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": "アプリのバージョンが更新されてデータアクセス範囲が追加されています。再度認可をしてください。",
}