台帳堂Daichodo

エラー

エラーの形式は共通です。常に 5 つのフィールドを返します。

{
  "type": "https://daichodo.com/errors/not_found",
  "code": "not_found",
  "message": "No invoice issuer with registration number T8000000000001",
  "doc_url": "https://daichodo.com/docs/errors/#not_found",
  "request_id": "req_01J8XZ9Q7M4KDR"
}

code が機械可読の識別子です。ステータスコードではなく code で分岐してください。 429 は 2 種類のエラーが共有しており、対処が逆になります。

message は人が読むための説明で、予告なく変更されます。解析しないでください。 type はエラー種別を示す安定した URI、doc_url はこのページの該当セクションを指します。お問い合わせの際は request_id をお知らせください。ログ上の該当リクエストを特定できます。

6 つ目のフィールド details は、該当するコードにのみ付きます。中身がない場合は null ではなくフィールドごと省略されるため、値ではなく存在の有無で判定してください。

エラーコード

HTTPcode再試行内容
400invalid_number不可番号の形式が不正です
401unauthorized不可キーが未指定・不正・失効
403plan_required不可上位プランが必要な機能です
404not_found不可形式は正しいが登録簿に存在しません
422invalid_request不可リクエスト自体の形式が不正です
429rate_limited可1 分あたりの呼び出し回数の超過
429quota_exceeded不可月間の上限に到達しました
5xxinternal_error可当方の問題です

invalid_number — 400

法人番号または登録番号として形式が正しくありません。どの検査に失敗したかは message に入ります。多くはチェックディジットです。呼び出す前に検証を行えば発生しません。検証は無料で、回数も消費しません。

not_found とは区別されます。400 と 404 の違いをご覧ください。

unauthorized — 401

キーが未指定、存在しない、または失効しています。同じキーで再試行しても結果は変わりません。キーは app.daichodo.com で発行できます。

plan_required — 403

キー自体は有効ですが、そのプランに含まれない機能です。再試行しても同じ結果で、照会回数だけを消費します。details が付きます。

{
  "code": "plan_required",
  "message": "point_in_time requires the standard plan; this key is on the free plan.",
  "details": {
    "capability": "point_in_time",
    "required_plan": "standard",
    "current_plan": "free",
    "upgrade_url": "https://daichodo.com/pricing"
  }
}

文章を解析するのではなく required_plan で分岐してください。エージェントが再試行せずに「何が必要か」を利用者に伝えられるのは、このフィールドがあるためです。

not_found — 404

形式は正しく、該当する記録が存在しません。これは失敗ではなく業務上の回答です。その相手は適格請求書発行事業者ではない、ということを意味します。

name が null の個人事業者の記録は、これには該当しません。記録は見つかっています。国税庁が公表データから個人の識別情報を除いているためで、日付の項目はそのまま有効です。照会をご覧ください。

invalid_request — 422

リクエスト自体の形式が不正です。パラメータの不足や解釈不能、リクエストボディの不備、日付として解釈できない値などが該当します。対象のフィールドは message に入ります。 invalid_number が「番号の値」の問題であるのに対し、こちらは「呼び出しの形」の問題です。

rate_limited — 429

1 分あたりの呼び出し回数を超えました。ウィンドウが切り替われば再試行できます。 details が付きます。

{
  "code": "rate_limited",
  "message": "Rate limit of 60 requests per minute exceeded. Retry in 12s.",
  "details": { "limit_per_minute": 60, "retry_after": 12 }
}

バックオフを推測せず retry_after に従ってください。ヘッダーのみを読む実装向けに、 Retry-After ヘッダーでも同じ値を返します。

quota_exceeded — 429

月間の照会枠を使い切りました。rate_limited と同じ 429 ですが、再試行はできません。 月が変わるかプランを変更するまで同じ結果が返ります。ステータスではなく code で分岐すべき理由がこれです。

消費されるのは登録簿への照会のみです。検証は無料かつ無制限で、自分の残枠の確認も、該当なしに終わった照会も消費しません。

internal_error — 5xx

当方の問題です。指数バックオフで再試行してください。message は意図的に一般化しています。request_id をお知らせいただければ該当リクエストを特定できます。

400 と 404 の違い

400 は「それは番号ではない」、404 は「番号ではあるが、登録されていない」です。

区別されているのは、取るべき対応が違うからです。前者は入力の誤りであり、後者は業務上の回答です。その相手は適格請求書発行事業者ではありません。

再試行について

5xx と rate_limited は指数バックオフで再試行してください。retry_after が返る場合はその値に従ってください。

quota_exceeded は 429 ですが再試行しないでください。 その他の 4xx も再試行しても同じ結果が返ります。