※ 本記事はfreee勤怠管理Plusについてのヘルプページです。freee人事労務については「freee人事労務のカテゴリー」をご覧ください。
直接WebAPI利用においてエラーが発生する場合に考えられる原因と対処方法を解説します。直接WebAPI利用について詳細は「API連携サービス以外に、直接WebAPIを利用する方法」のヘルプページをご参照ください。
API連携サービスやCSV連携をご利用の場合
API連携サービスやCSV連携においてエラーが発生する場合は、「外部連携（API連携サービス、CSV連携）に失敗する場合の確認事項」のヘルプページをご参照ください。
目次
-
アクセスや認証に失敗する
- 【ケース1】WebAPI制限時間帯にリクエストしている
- 【ケース2】メンテナンス中にリクエストしている
- 【ケース3】許可IPアドレスが未設定 / 誤っている
- 【ケース4】アクセストークンの指定が誤っている
- 【ケース5】連携希望項目に権限が付与されていない -
リクエスト数に関するエラーが出る
- 【ケース1】レート制限を超過するリクエストを送っている
- 【ケース2】リクエストが集中している -
データの取得に失敗する
- 【ケース1】特定の従業員や管理者のデータ取得に失敗する
- 【ケース2】対象データがない
- 【ケース3】パラメーターの指定に問題がある -
データの登録 / 更新に失敗する
- 【ケース1】従業員のデータ登録 / 更新に失敗する
- 【ケース2】対象データがない
- 【ケース3】パラメーターやメソッドの指定に問題がある
- 【ケース4】スケジュールの更新に失敗する
アクセスや認証に失敗する
次のように「アクセスが禁止されています」「Resource Serer Error」「認証に失敗しました」となる場合の原因と対処方法です。
エラー例：
- HTTP STATUS 403
"message": "次の時間帯（JST）はAPIへのアクセスが禁止されています
[08:30 ～ 10:00, 17:30 ～ 18:30]",
"code": 104 - HTTP STATUS 500
"message": "Resource Server Error.",
"code": 300 - HTTP STATUS 403
"message": "認証に失敗しました",
"code": 100
【ケース1】WebAPI制限時間帯にリクエストしている
原因
以下のWebAPI制限時間帯には、アクセストークンと打刻登録以外のWebAPIを利用できません。
- 制限時間帯 8:30～10:00 / 17:30～18:30
対処方法
WebAPI制限時間帯以外の時間帯においてリクエストしてください。
【ケース2】メンテナンス中にリクエストしている
原因
freee勤怠管理Plusのメンテナンス中はWebAPIを利用できません。
対処方法
メンテナンス終了後にリクエストしてください。
【ケース3】許可IPアドレスが未設定 / 誤っている
原因
freee勤怠管理Plus WebAPI連携設定画面 ＞ 各WebAPI連携設定 ＞ 許可IPアドレス には、接続元グローバルIPアドレスの設定が必須です。未設定や誤ったIPアドレスを設定した場合、アクセスが許可されずエラーになります。
対処方法
「【WebAPI】IPアドレスの確認 / 登録 / 範囲指定方法」のヘルプページを参照し、許可IPアドレスに接続元グローバルIPアドレスを設定してください。
- 他社サービスをご利用の場合、他社IPアドレスの設定が必要なことがあります。
- 外部通信を行うIPアドレスを社内で固定している、または動的IPアドレスを使用しているなどの場合、ご認識と異なるIPアドレスからアクセスしていることがあります。接続元IPアドレスの確認をご希望の場合は「API実施日時」と「アクセストークン」をご記載のうえ、サポートセンターまでご依頼ください。
【ケース4】アクセストークンの指定が誤っている
原因
freee勤怠管理Plus WebAPI連携設定画面 ＞ 各WebAPI連携設定 ＞アクセストークン と一致しないアクセストークンを指定すると、エラーになります。またアクセストークンは次のようにAuthorization リクエストヘッダに含める必要があります。
Authorization: Bearer アクセストークン
対処方法
「【WebAPI】既存アクセストークンの確認方法」のヘルプページを参照し、アクセストークンをご確認ください。またアクセストークン前に「Bearer」と半角スペースを設定してください。
アクセストークンの期限
発行されたアクセストークンは無制限で利用できます。
freee勤怠管理Plus WebAPI連携設定画面 ＞ 各WebAPI連携設定 ＞ アクセストークン に該当アクセストークンが存在しない場合、該当アクセストークンを誤って削除した可能性があります。［＋新規アクセストークン発行］をクリックし、必要項目を入力してアクセストークンを再発行してください。操作の詳細は「API連携サービス以外に、直接WebAPIを利用する方法 - 新規アクセストークン発行」のヘルプページをご参照ください。
【ケース5】連携希望項目に権限が付与されていない
原因
WebAPIの連携希望項目に必要な権限（Read / Write）が付与されていないと、エラーになります。
対処方法
「API連携サービス以外に、直接WebAPIを利用する方法 - 新規アクセストークン発行」の「API権限情報」を参照し、連携希望項目の「Read」や「Write」にチェックを入れてください。
リクエスト数に関するエラーが出る
次のようにリクエスト数に関するエラーが出る場合の原因と対処方法です。
エラー例：
- HTTP STATUS 403
"message": "期間内でのリクエスト数の上限に達しています 少し経ってから再度リクエストしてください",
"code": 105 - HTTP STATUS 429
"message": "Too Many Requests",
"code": 303 - HTTP STATUS 403
"message": "Forbidden.",
"code": 407
【ケース1】レート制限を超過するリクエストを送っている
原因
freee勤怠管理Plusでは次のレート制限を実施しています。これらのレートを超過した場合は「リクエスト数の上限に達しています」エラーとなります。
【企業単位のレート制限】
| 対象エンドポイント | 制限内容 |
|---|---|
| トークンエンドポイント、および 日別打刻データ（POST） 以外のすべて ※すべてのAPIリクエストを合算して対象とします。 |
直近5分で500リクエスト |
| 日別打刻データ（POST） ※単体制限です。 |
直近5分で2,000リクエスト |
対処方法
リクエストが制限に抵触しないよう、時間帯を分けてリクエストを送る、不要なリクエストを整理するなどをご検討ください。
【ケース2】リクエストが集中している
原因
短時間において大量のリクエストが集中してサーバーの負荷が高くなっている場合、サービスの可用性を担保するため「Too Many Requests」などのエラーが返されます。
対処方法
時間をおいてリクエストを実施してください。
リクエストは並列で同時に送信しないでください。1件ずつ送信し、目安として1秒ほど送信間隔を空けてください。
データの取得に失敗する
データの取得に失敗する場合の原因と対処方法です。
【ケース1】特定の従業員や管理者のデータ取得に失敗する
原因
特定の従業員や管理者のデータを取得する際は、識別キーの指定が必要です。識別キーが誤っていると「400 Bad Request」エラーとなります。また識別キーを指定せずにデータを取得すると、全従業員、全管理者のデータが取得されます。
対処方法
正しい識別キーを指定しているか、ご確認ください。
【ケース2】対象データがない
原因
次のような場合はサーバーに取得対象データがないため、「204 No content」が返されます。連携先API側でレスポンスがNULLや空の場合の処理が考慮されていない場合、エラーとなります。
- スケジュール登録していない日を対象に、日別スケジュールデータを取得している
- 休暇残日数がない状態で、残休暇データを取得している
対処方法
連携先API側でレスポンスがNULLや空の場合の処理を考慮するよう、調整してください。
【ケース3】パラメーターの指定に問題がある
原因
次のようにパラメーターの指定に問題がある場合は、「400 Bad Request」エラーとなります。
- 日付指定の形式が正しくない
- パラメーターの記述が誤っている
エラー例：
- HTTP STATUS 400
"message": "Failed to decode json",
"code": 204 - HTTP STATUS 400
"message": "Dateの形式が正しくありません(yyyy-MM)",
"code": 2
対処方法
パラメーターの指定に誤りがないか、ご確認ください。
データの登録 / 更新に失敗する
データの登録や更新に失敗する場合の原因と対処方法です。
【ケース1】従業員のデータ登録 / 更新に失敗する
原因
- 従業員を登録する際は、既存の従業員と重複していない従業員コードを指定する必要があります。既存の従業員コードを指定して従業員を登録すると「The employee code is duplicated with the other employee」エラーとなります。
- 特定の従業員のデータを更新する際は、識別キーの指定が必要です。識別キーが誤っていると「400 Bad Request」エラーとなります。
対処方法
- 退職者も含め、従業員コードが重複していないか確認してください。退職者と同じ従業員コードを設定したい場合は、該当退職者を削除してください。従業員の削除方法については、「従業員の削除方法 / 復旧方法」のヘルプページをご参照ください。
- 正しい識別キーを指定しているか、ご確認ください。
【ケース2】対象データがない
原因
次のような場合はサーバーに対象データがないため、「204 No content」が返されます。連携先API側でレスポンスがNULLや空の場合の処理が考慮されていない場合、エラーとなります。
- 退勤打刻の自動上書き機能が「使用する」になっている状態で、既存の退勤打刻より前の退勤打刻を登録している
対処方法
連携先API側でレスポンスがNULLや空の場合の処理を考慮するよう、調整してください。
【ケース3】パラメーターやメソッドの指定に問題がある
原因
パラメーターの指定に問題がある場合や、指定されているメソッドと異なるメソッドでリクエストした場合は、「400 Bad Request」または「405 Method Not Allowed」エラーとなります。
- 勤務日と休憩開始の日付がずれているデータを登録しようとしている
- パラメーターの記述が誤っている
- PUTで指定する内容をPOSTでリクエストした
エラー例：
- HTTP STATUS 405
"message": "Code:405 Reason:Method Not Allowed",
"code": 400
対処方法
パラメーターやメソッドの指定に誤りがないか、ご確認ください。
【ケース4】スケジュールの更新に失敗する
原因
従業員による振休申請、または管理者による振休設定にて、振替休日または振替出勤日に指定している日（申請中を含む）を対象としている場合、スケジュール更新ができず、「It has been designated as either a substitute holiday or a substitute working day」エラーとなります。
振休申請について詳細は下記ヘルプページをご参照ください。
対処方法
振替休日または振替出勤日の変更や取り消しを行ったうえで、再度登録してください。