直接WebAPI利用においてエラーが発生する場合に考えられる原因と対処方法を解説します。
目次
- アクセスや認証に失敗する
- 【ケース1】WebAPI制限時間帯にリクエストしている
- 【ケース2】メンテナンス中にリクエストしている
- 【ケース3】許可IPアドレスが未設定 / 誤っている
- 【ケース4】アクセストークンの指定が誤っている
- 【ケース5】連携希望項目に権限が付与されていない
- リクエスト数に関するエラーが出る
- データの取得に失敗する
- データの登録 / 更新に失敗する
アクセスや認証に失敗する
次のように「アクセスが禁止されています」「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】メンテナンス中にリクエストしている
原因
KING OF TIME 勤怠管理のメンテナンス中はWebAPIを利用できません。
対処方法
「リリース予定 / メンテナンス情報」にてメンテナンス情報を確認し、メンテナンス終了後にリクエストしてください。
KING OF TIME 勤怠管理サーバーの稼働状況について
KING OF TIME 勤怠管理サーバーが正常に稼働していない場合も、WebAPIを利用できません。メンテナンス情報がない場合は、こちらで稼働状況をご確認ください。
【ケース3】許可IPアドレスが未設定 / 誤っている
原因
KING OF TIME 勤怠管理 WebAPI連携設定画面 > 各WebAPI連携設定 > 許可IPアドレス には、接続元グローバルIPアドレスの設定が必須です。未設定や誤ったIPアドレスを設定した場合、アクセスが許可されずエラーになります。
対処方法
こちらを参照し、許可IPアドレスに接続元グローバルIPアドレスを設定してください。
ご注意
- 他社サービスをご利用の場合、他社IPアドレスの設定が必要なことがあります。
- 外部通信を行うIPアドレスを社内で固定している、または動的IPアドレスを使用しているなどの場合、ご認識と異なるIPアドレスからアクセスしていることがあります。接続元IPアドレスの確認をご希望の場合は「API実施日時」と「アクセストークン」をご記載のうえ、サポートセンターまでご依頼ください。
【ケース4】アクセストークンの指定が誤っている
原因
KING OF TIME 勤怠管理 WebAPI連携設定画面 > 各WebAPI連携設定 >アクセストークン と一致しないアクセストークンを指定すると、エラーになります。またアクセストークンは次のようにAuthorization リクエストヘッダに含める必要があります。
Authorization: Bearer アクセストークン
対処方法
こちらを参照し、アクセストークンをご確認ください。またアクセストークン前に「Bearer」と半角スペースを設定してください。
アクセストークンの期限
発行されたアクセストークンは無制限で利用できます。
ご注意
KING OF TIME 勤怠管理 WebAPI連携設定画面 > 各WebAPI連携設定 > アクセストークン に該当アクセストークンが存在しない場合、該当アクセストークンを誤って削除した可能性があります。[+新規アクセストークン発行]をクリックし、必要項目を入力してアクセストークンを再発行してください。操作の詳細はこちらをご参照ください。
【ケース5】連携希望項目に権限が付与されていない
原因
WebAPIの連携希望項目に必要な権限(Read / Write)が付与されていないと、エラーになります。
対処方法
こちらの「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】レート制限を超過するリクエストを送っている
原因
KING OF TIME 勤怠管理では次のレート制限を実施しています。これらのレートを超過した場合は「リクエスト数の上限に達しています」エラーとなります。
企業単位のレート制限:
対象エンドポイント | 制限内容 |
---|---|
トークンエンドポイント、および 日別打刻データ(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】異動日の登録に失敗する
原因
従業員の所属や雇用区分を登録する際は、次の2つの条件を満たす異動日のみ指定できます。異動日がこれらの条件に合致しない場合、登録に失敗します。
- 当月度の開始日以降
- 勤怠締め済み期間の最終日より後
対処方法
- 初回登録した雇用区分を変更したい場合や、当月度の開始日より前の日を異動日に指定したい場合は、所属・雇用区分の変更履歴編集制限の制限解除が必要です。詳細はこちらの「補足」をご参照ください。
- 勤怠締め済み期間の最終日より前の日を異動日に指定したい場合は、勤怠の締めを解除してください。詳細はこちらをご参照ください。