エラーコード
失敗した呼び出しには、HTTP ステータスと JSON エンベロープが返され、エンベロープの code に問題の内容が示されます。API が返すコードは、次の 25 種類ですべてです。v1 の範囲内でも新しいコードが追加されることがあります。未知のコードは HTTP ステータスに従って扱ってください。
エラーエンベロープ
エラーのボディはすべてこの形式です。code と message は常に含まれます。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| error | object | はい | |
| error.code | string | はい | Machine-readable error code. Each response lists the codes it can carry; new codes may be added within v1, so treat an unknown code by its HTTP status. |
| error.message | string | はい | Human-readable explanation (English). |
| error.requestId | string | いいえ | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | いいえ | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | いいえ | Where the error codes are explained. Sent since v1.1.
|
必須フィールドを省略したリクエストに対する、実際のエラーレスポンス：
curl -sS 'https://ecdsa.com/api/v1/jwt/decode' \
-H 'content-type: application/json' \
-d '{}'{
"error": {
"code": "missing_field",
"message": "Field \"token\" is required and must be a non-empty string.",
"requestId": "docs-example",
"docs": "https://ecdsa.com/developers#errors"
}
}全コード一覧
| コード | HTTP | 意味 | 発生する状況 | 対処法 | SDK |
|---|---|---|---|---|---|
| invalid_json | 400 | The body is not valid JSON or not a JSON object; or the input nests arrays and objects more than 64 levels deep (JSON documents inside string fields count too), or is too complex to inspect for private keys. | よくある原因は、ボディが JSON ではなくフォームエンコード形式やプレーンテキストになっていること、トップレベルが JSON の配列や文字列になっていること、または自動生成した入力のネストが非常に深いことです。content-type ヘッダーは関係なく、判定の対象はボディです。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | ボディには単一の JSON オブジェクトを送信してください。入力を自動生成している場合は、ネストの深さを確認してください。 | 再試行なし |
| missing_field | 400 | A required field is absent or empty. | 操作に必須のフィールドが存在しない、null、空、または文字列ではない場合です。publicKey を public_key と書くなど、名前の綴りが違っていることがよくあります。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | メッセージに示されたフィールドを追加してください。必須フィールドは、その操作のリファレンスページに一覧があります。 | 再試行なし |
| invalid_input | 400 | A field could not be parsed — the message explains exactly why. | フィールドはあるものの、解析できない場合です。鍵、署名、トークン、証明書が、その操作の認識できないエンコーディングまたは形式になっています。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint | メッセージを確認してください。フィールドと理由が示されています。エンコーディング（hex、base64、PEM）と、署名の場合は曲線を確認してください。 | 再試行なし |
| private_key_rejected | 400 | The request contains private-key material (a PEM PRIVATE KEY block, an OpenSSH, SSH2 or PuTTY private key, or a JWK with "d"). Never send private keys anywhere. | 公開鍵だけが必要な場所に、鍵ファイル全体を貼り付けた場合です。PKCS#8 や SEC1 の PEM、OpenSSH や PuTTY の秘密鍵、「d」が残ったままの JWK が該当し、JSON を格納した文字列の中にネストされている場合も含みます。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | 公開データだけを送信してください。秘密鍵を扱う場合は、ブラウザーのツールを使ってください。ツールは手元のマシン上で動作し、何も送信しません。 | 再試行なし |
| unsupported_algorithm | 400 | The token's algorithm is not one this operation verifies. | その操作が検証に対応していないアルゴリズム（HS*、RS*、PS*、EdDSA、ES256K、none）の JWT を送った場合です。 | この API が検証するのは ES256、ES384、ES512 です。ほかのアルゴリズムは、JWT ライブラリを使ってローカルで検証してください。HMAC のシークレットは、どこにも送信してはいけません。 | 再試行なし |
| invalid_domain | 400 | Not a public DNS hostname (IP addresses, single-label names and paths are refused). | パスセグメントが、IP アドレス、localhost のようにドットを含まない名前、またはホスト名ではない文字列の場合です。名前の前後にあるスキーム、ポート、パスは先に取り除かれます。 | github.com のような公開ホスト名を送信してください。IP アドレスや内部の名前は、ここからはスキャンできません。 | 再試行なし |
| scan_dns_error | 400 | The domain does not resolve in public DNS. | 公開 DNS で名前を解決できない場合です。原因は、ドメインが存在しない（入力ミス、登録の期限切れ、内部 DNS にしかない名前）、A レコードも AAAA レコードもない、または DNS の障害です。 | 綴りと、その名前に A または AAAA レコードがあることを確認してください。 | 再試行なし |
| scan_private_address | 400 | The domain resolves (at least partly) to a private or reserved address. | 名前のアドレスのいずれか（IPv4、IPv6、または IPv6 に埋め込まれた IPv4）が、内部ネットワークやループバックなどのプライベートまたは予約済みの範囲にある場合です。パブリックアドレスとプライベートアドレスが混在している場合は、全体が拒否されます。 | パブリックなインターネットから到達できるホストをチェックしてください。内部ホストはここからはスキャンできません。 | 再試行なし |
| webhook_url_refusedAPI キー導入後 | 400 | The webhook URL cannot receive deliveries: it is not https on port 443, its host is not a public DNS name, or the name does not resolve or resolves (at least partly) to a private or reserved address. | エンドポイントの作成時に、http の URL、443 以外のポート、IP アドレスや内部の名前、または DNS の応答にプライベートアドレスや予約済みアドレスを含むホストを指定した場合です。複数のアドレスのうち 1 つだけが該当する場合も同様です。 | デフォルトのポートと公開ホスト名を使った https の URL を指定してください。メッセージには、URL が違反したルールと、アドレスが拒否された場合はそのアドレスと範囲が示されます。 | 再試行なし |
| unauthorized | 401 | The Authorization or X-API-Key header is malformed, the API key is not valid (wrong checksum, unknown, revoked or expired), or the operation needs a key. |
操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | 匿名で呼び出す場合はヘッダーを削除し、そうでなければ完全で有効なキーを送信してください。 | 再試行なし |
| forbidden_scopeAPI キー導入後 | 403 | The API key is valid but lacks a scope this operation requires; the message names it. | 操作に必要なスコープなしで作成されたキーを使った場合です。たとえば、scan スコープが必要なドメインのヘルスチェックの操作を、api スコープしか持たないキーで呼び出した場合が該当します。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | そのスコープを持つキーで呼び出してください。 | 再試行なし |
| webhook_limit_reachedAPI キー導入後 | 403 | The account already has as many webhook endpoints as its plan allows. | アカウントにプランの上限数のエンドポイントがすでにある状態で、エンドポイントを作成した場合です。無料プランの上限は 1 つです。 | 不要になったエンドポイントを削除してください。既存のエンドポイントの説明やイベントを変更する場合は、同じ URL で作成し直してください。 | 再試行なし |
| not_found | 404 | No operation exists at this path. |
どの操作でも返される可能性があります。 | パスを API リファレンスと照らし合わせて確認してください。操作は /api/v1 の下にあります。 | 再試行なし |
| webhook_not_foundAPI キー導入後 | 404 | The API key's account has no webhook endpoint with this id. | エンドポイントの ID が、キーのアカウントに属していない場合です（削除済み、入力ミス、または別のアカウントのもの）。 | GET /api/v1/webhooks でアカウントのエンドポイントを一覧表示し、その中の ID を使ってください。 | 再試行なし |
| method_not_allowed | 405 | The path exists but does not accept this HTTP method; see the Allow header. | POST の操作を GET で呼び出した場合（たとえば、ブラウザーのアドレスバーで開いた場合）、またはその逆の場合です。 どの操作でも返される可能性があります。 | Allow ヘッダーに示されたメソッドを使ってください。JSON ボディを受け取る操作は POST、それ以外は GET です。 | 再試行なし |
| payload_too_large | 413 | The body exceeds 100 KB. | ボディが 100 KB を超えている場合です。多くは、証明書バンドルやファイル全体を 1 つのフィールドに貼り付けたことが原因です。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | 1 回の呼び出しで送る量を減らしてください（証明書チェーンもトークンも 1 つずつ）。 | 再試行なし |
| rate_limited | 429 | Too many requests — see Retry-After. | 現在の時間枠でリクエストが多すぎる場合です。キーなしでは IP ごと、キーありではキーごとに数えます。ドメインの実際のスキャンは、ホストごとの枠と全体の枠も消費します。 操作： API self-description, Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | Retry-After に示された秒数だけ待ってから再試行し、利用側でもレスポンスをキャッシュしてください。 | 最大 2 回再試行 |
| quota_exceededAPI キー導入後 | 429 | A daily or monthly quota of the API key's account is used up. X-Quota-Reset (and Retry-After) say when it starts over; retrying earlier cannot succeed. | キーを使った呼び出しで、アカウントの日次・月次のクォータユニット、または日次のドメインスキャン数を使い切った場合です。テスト用キーには、より小さい独自のクォータがあります。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | X-Quota-Reset に示された時刻より前に再試行しないでください。クォータがリセットされるのはその時刻で、それより早くはなりません。 | 再試行なし |
| internal_error | 500 | Unexpected server error. | API が想定していない障害です。リクエスト ID とともにログに記録されますが、リクエストボディが記録されることはありません。 どの操作でも返される可能性があります。 | 問題が続く場合は、エラーボディの requestId を添えて報告してください。 | 再試行なし |
| scan_unreachable | 502 | The domain refused or dropped the connection on port 443. | 名前は解決できるものの、インターネットからポート 443 への TCP 接続がどれも成功しない場合です。原因は、HTTPS サーバーがない、ファイアウォールが接続を拒否または破棄している、またはホストが停止していることです。 | ホストがパブリックなインターネットに向けて、ポート 443 で HTTPS を提供していることを確認してください。 | 最大 2 回再試行 |
| scan_tls_error | 502 | The TLS handshake failed or presented no usable certificate. | ポート 443 への接続は確立するものの、TLS ハンドシェイクがアラートまたはプロトコルの不一致で終了する場合、またはサーバーがスキャナーで読み取れる証明書を送信しない場合です。 | サーバーの TLS 設定を確認してください。たとえば、ドメインのヘルスレポートで確認できます。 | 最大 2 回再試行 |
| service_unavailableAPI キー導入後 | 503 | API keys cannot be verified right now (the key store is unreachable); retry shortly. | キーストアに接続できないため、提示されたキーを確認できない場合です。キーを提示した呼び出しが匿名として処理されることはありません。 操作： Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | 少し待ってから再試行してください。SDK は自動で再試行します。 | 最大 2 回再試行 |
| webhooks_unavailableAPI キー導入後 | 503 | Webhooks are switched off on this server: it has no signing keys configured. | サーバーに webhook の署名鍵が設定されていないため、配信に署名できない場合です。鍵が設定されるまで、webhook のすべての操作がこのコードを返します。 操作： List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | リクエストを変更する必要はありません。このサーバーでは現在 webhook が無効になっています。後でもう一度試してください。 | 最大 2 回再試行 |
| scan_timeout | 504 | The scan did not finish in time. | 名前解決、接続、または TLS ハンドシェイクに、スキャナーの許容時間より長くかかった場合です。原因は、ホストの応答が遅いか過負荷になっていること、またはパケットが通知なく破棄されていることです。 | 後で再試行してください。応答が遅いホストや過負荷のホストでは、制限時間を超えることがあります。 | 最大 2 回再試行 |
| timeout | 504 | The operation did not finish within its time budget. | リクエストの処理が、制限時間の 10 秒を超えた場合です。リクエストの制限内に収まる入力で、これが起こることは想定されていません。 操作： API self-description, Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event | 一度だけ再試行してください。同じ入力で再びタイムアウトした場合は、エラーボディの requestId を添えて報告してください。 | 最大 2 回再試行 |
再試行
公式 SDK は、429（quota_exceeded を除く）、502、503、504 を最大 2 回再試行します。待機時間は Retry-After の指定に従い（最大 60 秒）、指定がない場合はフルジッター付きの指数バックオフを使います。どの操作も入力だけで結果が決まる純粋関数なので、再試行は常に安全です。独自のクライアントでも同じルールに従うことができます。