跳到內容

錯誤與輪詢

串接 TCS API for DIW 時,下面幾種情況最常見。每支 API 的完整狀態碼表在本頁最後。錯誤回應的格式見 API 基礎。

發證和驗證的結果都要您自己查詢,系統不會主動通知您。

  • QR code 顯示在畫面上的期間,每 2 到 5 秒查詢一次。
  • 自己設逾時,建議 5 分鐘。

收證者或持卡人沒有掃描,或數位憑證皮夾(TW DIW,以下簡稱錢包)不讓持卡人選擇憑證時,在您設定的逾時內都會是 pending(等待中)。

逾時到了之後怎麼做,發證和驗證不同:

  • 發證:逾時只結束您的等待畫面,不會取消發證,收證者(領取後就是持卡人)之後仍可能掃描原本的 QR code。請保留原本的 id,重新發證前先再查一次它的狀態。細節見發證 API。
  • 驗證:停止查詢,請持卡人重新開始。

驗證完成大約 5 分鐘後,結果會清除,之後查詢回 410。結果拿不回來,請建立新的驗證請求。照上一節的建議頻率輪詢,通常能在清除前拿到結果。

錢包不會讓持卡人出示已撤銷的憑證。在您設定的逾時內都會是 pending(等待中),或持卡人出示同一種憑證類型的另一張憑證,您收到驗證通過(verify_result: true)。請確認 data[].cid 等於您發證後存下的 credential_serial,也要照樣設定逾時。細節見撤銷 API。

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:多數情況是 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 基礎。

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 的格式。
10113issuance_date 是未來的日期改成今天或之前的日期,或不帶這個欄位。
10114expired_date 早於今天,或早於憑證類型的建立日期改成較晚的日期。

message 裡的說明文字照原文轉給您,可能是中文或英文。表上沒有的錯誤碼,請帶請求時間與 x-correlation-id 聯絡 TCS 團隊。

狀態碼意思您要做的事
201已建立。回 id、qrcode_image、deep_link、warnings。顯示 QR code,開始輪詢。
400欄位格式不對(不是陣列、值不是字串、日期不是 8 位數字、有多餘欄位、cids 裡有不是整串的 cid),或請求被拒絕(message 開頭是 issuer module)。照錯誤訊息修正;錯誤碼見上方表格。
401API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。見 API 基礎。
404credential not found:cids 裡有不屬於您帳號的 cid。檢查 cids。
502 或沒有回應沒有正常完成。發證可能已經建立。不要自動重送。 帶請求時間與 x-correlation-id/x-request-id 的值 聯絡 TCS 團隊。
狀態碼意思您要做的事
200 pending收證者還沒領取。2 到 5 秒後再查。
200 issued收證者已經領取。回 credential、cid、credential_serial。存下 cid 與 credential_serial。
400id 格式不對(id is not an issuance id),或請求被拒絕(message 開頭是 issuer module)。檢查是否帶了建立時拿到的整串 id。
401API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。見 API 基礎。
404issuance not found:id 不存在、不屬於您的帳號,或被改過。檢查 id。
502TCS 這一端沒有正常完成。可以重送。
狀態碼意思您要做的事
201已建立。回 id、qrcode_image、auth_uri。顯示 QR code,開始輪詢。
400ref 缺少、是空字串或不是字串;body 有多餘欄位;或驗證情境不接受這個請求(message 開頭是 verifier module)。檢查 ref,以及 body 是否只有 ref。
401API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。見 API 基礎。
502TCS 這一端沒有正常完成。可以重送。

查詢驗證 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 決定。
400id 格式不對(id is not a verification id),或請求被拒絕(message 開頭是 verifier module)。檢查是否帶了建立時拿到的整串 id。
401API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。見 API 基礎。
404verification not found:id 不屬於您的帳號,或被改過。檢查 id。
410結果已清除。建立新的驗證請求。
502TCS 這一端沒有正常完成。可以重送。

撤銷 POST /v1/diw/credentials/{cid}/revoke

Section titled “撤銷 POST /v1/diw/credentials/{cid}/revoke”
狀態碼意思您要做的事
201已撤銷。回 cid、credential_status: REVOKED。更新您的紀錄。
400cid 格式不對(cid is not a credential id),或 API 拒絕這次撤銷(message 開頭是 issuer module),例如這張憑證已經撤銷過(issuer module 30205)。重送後才收到的,見撤銷 API。其他情況,cid 格式不對時檢查 cid;message 開頭是 issuer module 時,帶請求時間與 x-correlation-id 聯絡 TCS 團隊。
401API Key 有問題,或 TCS 這一端檢查 key 時出錯(Authentication failed)。見 API 基礎。
404credential not found:cid 不屬於您的帳號,或被改過。檢查 cid。
502TCS 這一端沒有正常完成。撤銷可能已經完成。可以重送。