錯誤與輪詢
串接 TCS API for DIW 時,下面幾種情況最常見。每支 API 的完整狀態碼表在本頁最後。錯誤回應的格式見 API 基礎。
輪詢一直是 pending
Section titled “輪詢一直是 pending”發證和驗證的結果都要您自己查詢,系統不會主動通知您。
- QR code 顯示在畫面上的期間,每 2 到 5 秒查詢一次。
- 自己設逾時,建議 5 分鐘。
收證者或持卡人沒有掃描,或數位憑證皮夾(TW DIW,以下簡稱錢包)不讓持卡人選擇憑證時,在您設定的逾時內都會是 pending(等待中)。
逾時到了之後怎麼做,發證和驗證不同:
- 發證:逾時只結束您的等待畫面,不會取消發證,收證者(領取後就是持卡人)之後仍可能掃描原本的 QR code。請保留原本的
id,重新發證前先再查一次它的狀態。細節見發證 API。 - 驗證:停止查詢,請持卡人重新開始。
驗證結果過期(410)
Section titled “驗證結果過期(410)”驗證完成大約 5 分鐘後,結果會清除,之後查詢回 410。結果拿不回來,請建立新的驗證請求。照上一節的建議頻率輪詢,通常能在清除前拿到結果。
撤銷後再驗證會看到什麼
Section titled “撤銷後再驗證會看到什麼”錢包不會讓持卡人出示已撤銷的憑證。在您設定的逾時內都會是 pending(等待中),或持卡人出示同一種憑證類型的另一張憑證,您收到驗證通過(verify_result: true)。請確認 data[].cid 等於您發證後存下的 credential_serial,也要照樣設定逾時。細節見撤銷 API。
收到 502
Section titled “收到 502”502 表示這次請求沒有正常完成,原因在 TCS 這一端,不是您的請求內容。TCS 這一端處理超過 5 秒沒有完成,也回 502。
502 不代表操作沒有發生。能不能重送,看是哪支 API:
| API | 收到 502 時 |
|---|---|
建立發證 POST /v1/diw/issuances | 不要自動重送。 發證可能已經建立。記下請求時間和 x-correlation-id/x-request-id 的值,聯絡 TCS 團隊。 |
查詢發證 GET /v1/diw/issuances/{id} | 可以重送。 |
建立驗證 POST /v1/diw/verifications | 可以重送。重送會產生新的 id,請改用新的 QR code。 |
查詢驗證 GET /v1/diw/verifications/{id} | 可以重送。 |
撤銷 POST /v1/diw/credentials/{cid}/revoke | 可以重送。重送回 400 且 message 開頭是 issuer module 30205,表示第一次已經撤銷成功,見撤銷 API。 |
建立發證時,HTTP client 逾時、連線中斷或沒有收到回應,都和 502 一樣處理:不要自動重送。如果您使用的 HTTP client、SDK 或 API gateway 會在請求失敗時自動重送,請對建立發證這支 API 關閉這個功能,避免同一筆發證被建立兩次。
收到其他 5xx(例如 500、503、504),處理方式和 502 相同。
502 的回應 body 有時不是 JSON,而是純文字(例如 error code: 502),這時您看不到 correlationId。請在送出前就把自己的 x-correlation-id 記進 log。
401 與 404
Section titled “401 與 404”401:多數情況是 API Key 有問題,message會說明是哪一種。Authentication failed是例外:這是 TCS 這一端檢查 key 時出錯。key 確定沒問題卻持續發生,請帶請求時間與x-correlation-id聯絡 TCS 團隊。對照表見 API 基礎。404,message是... not found:這個 id 屬於其他帳號,或被改過。查詢發證時,也可能是這筆發證不存在。請檢查您帶的是不是建立時拿到的整串 id。
每個請求都帶 x-correlation-id 與 x-request-id
Section titled “每個請求都帶 x-correlation-id 與 x-request-id”每個請求都帶 x-correlation-id,並把同一個值放進 x-request-id,用法見 API 基礎。
您可以自己修正的錯誤碼
Section titled “您可以自己修正的錯誤碼”API 拒絕請求內容時回 400。建立驗證時,message 的格式是 verifier module <錯誤碼>: <說明>;建立發證時是 issuer module <錯誤碼>: <說明>。下面這些是您可以從自己的請求修正的錯誤碼。10102 出現在建立驗證 POST /v1/diw/verifications,其餘都出現在建立發證 POST /v1/diw/issuances:
| 錯誤碼 | 意思 | 怎麼修正 |
|---|---|---|
10102 | 找不到這個驗證情境(查無模板資料) | 檢查 ref 是否和 TCS 團隊提供的代碼完全相同。 |
10108 | 找不到這個憑證類型(查無模板資料) | 檢查 vc_uid 是否和 TCS 團隊提供的代碼完全相同。 |
11007 | 這個憑證類型已經停止發行(VC 模版已停止發行) | 聯絡 TCS 團隊確認目前可用的 vc_uid。 |
11001 | 少了必填欄位,或必填欄位的值是空字串;vc_uid 不完整時也會回這個代碼 | 必填欄位都要放進 fields,而且要有值。vc_uid 請照 TCS 團隊提供的整串代碼填。選填欄位沒有值時,可以不帶,也可以帶空字串。 |
10112 | 帶了憑證類型沒有定義的欄位 | 拿掉多出來的 ename,或檢查拼字。 |
10110 | 欄位值不符合該欄位的規則 | 逐一檢查 content 是否符合各欄位的規則。訊息不會指出是哪個欄位,但會寫出沒有通過的規則,例如 只能輸入中英文數字和_。 |
10109 | 日期不是合法的 YYYYMMDD(例如 20261340) | 檢查 issuance_date 與 expired_date 的格式。 |
10113 | issuance_date 是未來的日期 | 改成今天或之前的日期,或不帶這個欄位。 |
10114 | expired_date 早於今天,或早於憑證類型的建立日期 | 改成較晚的日期。 |
message 裡的說明文字照原文轉給您,可能是中文或英文。表上沒有的錯誤碼,請帶請求時間與 x-correlation-id 聯絡 TCS 團隊。
完整狀態碼表
Section titled “完整狀態碼表”建立發證 POST /v1/diw/issuances
Section titled “建立發證 POST /v1/diw/issuances”| 狀態碼 | 意思 | 您要做的事 |
|---|---|---|
201 | 已建立。回 id、qrcode_image、deep_link、warnings。 | 顯示 QR code,開始輪詢。 |
400 | 欄位格式不對(不是陣列、值不是字串、日期不是 8 位數字、有多餘欄位、cids 裡有不是整串的 cid),或請求被拒絕(message 開頭是 issuer module)。 | 照錯誤訊息修正;錯誤碼見上方表格。 |
401 | API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。 | 見 API 基礎。 |
404 | credential not found:cids 裡有不屬於您帳號的 cid。 | 檢查 cids。 |
502 或沒有回應 | 沒有正常完成。發證可能已經建立。 | 不要自動重送。 帶請求時間與 x-correlation-id/x-request-id 的值 聯絡 TCS 團隊。 |
查詢發證 GET /v1/diw/issuances/{id}
Section titled “查詢發證 GET /v1/diw/issuances/{id}”| 狀態碼 | 意思 | 您要做的事 |
|---|---|---|
200 pending | 收證者還沒領取。 | 2 到 5 秒後再查。 |
200 issued | 收證者已經領取。回 credential、cid、credential_serial。 | 存下 cid 與 credential_serial。 |
400 | id 格式不對(id is not an issuance id),或請求被拒絕(message 開頭是 issuer module)。 | 檢查是否帶了建立時拿到的整串 id。 |
401 | API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。 | 見 API 基礎。 |
404 | issuance not found:id 不存在、不屬於您的帳號,或被改過。 | 檢查 id。 |
502 | TCS 這一端沒有正常完成。 | 可以重送。 |
建立驗證 POST /v1/diw/verifications
Section titled “建立驗證 POST /v1/diw/verifications”| 狀態碼 | 意思 | 您要做的事 |
|---|---|---|
201 | 已建立。回 id、qrcode_image、auth_uri。 | 顯示 QR code,開始輪詢。 |
400 | ref 缺少、是空字串或不是字串;body 有多餘欄位;或驗證情境不接受這個請求(message 開頭是 verifier module)。 | 檢查 ref,以及 body 是否只有 ref。 |
401 | API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。 | 見 API 基礎。 |
502 | TCS 這一端沒有正常完成。 | 可以重送。 |
查詢驗證 GET /v1/diw/verifications/{id}
Section titled “查詢驗證 GET /v1/diw/verifications/{id}”| 狀態碼 | 意思 | 您要做的事 |
|---|---|---|
200 pending | 持卡人還沒完成。 | 2 到 5 秒後再查。 |
200 completed | 有結果了。 | 讀 verify_result。驗證您發的憑證時,比對 data[].cid,方法見驗證 API;其他單位發的憑證,依 verify_result、credential_type 和 claims 決定。 |
400 | id 格式不對(id is not a verification id),或請求被拒絕(message 開頭是 verifier module)。 | 檢查是否帶了建立時拿到的整串 id。 |
401 | API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。 | 見 API 基礎。 |
404 | verification not found:id 不屬於您的帳號,或被改過。 | 檢查 id。 |
410 | 結果已清除。 | 建立新的驗證請求。 |
502 | TCS 這一端沒有正常完成。 | 可以重送。 |
撤銷 POST /v1/diw/credentials/{cid}/revoke
Section titled “撤銷 POST /v1/diw/credentials/{cid}/revoke”| 狀態碼 | 意思 | 您要做的事 |
|---|---|---|
201 | 已撤銷。回 cid、credential_status: REVOKED。 | 更新您的紀錄。 |
400 | cid 格式不對(cid is not a credential id),或 API 拒絕這次撤銷(message 開頭是 issuer module),例如這張憑證已經撤銷過(issuer module 30205)。 | 重送後才收到的,見撤銷 API。其他情況,cid 格式不對時檢查 cid;message 開頭是 issuer module 時,帶請求時間與 x-correlation-id 聯絡 TCS 團隊。 |
401 | API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。 | 見 API 基礎。 |
404 | credential not found:cid 不屬於您的帳號,或被改過。 | 檢查 cid。 |
502 | TCS 這一端沒有正常完成。撤銷可能已經完成。 | 可以重送。 |