Skip to content

Errors and Polling

These are the most common cases when you integrate with TCS API for DIW. The full status code table for each API is at the end of this page. For the error response format, see API Basics.

You must query the results of issuances and verifications yourself. The system does not notify you when a result is ready.

  • While the QR code is on the screen, query every 2 to 5 seconds.
  • Set your own timeout. The recommended value is 5 minutes.

If the recipient or the holder does not scan, or the Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook) does not let the holder select a credential, the status stays pending (waiting) for the full timeout that you set.

What you do after the timeout depends on whether you issue or verify:

  • Issuance: the timeout only closes your waiting screen. It does not cancel the issuance. The recipient (the holder after acceptance) may still scan the original QR code later. Keep the original id. Before you issue again, query its status once more. For details, see Issuance API.
  • Verification: stop polling and ask the holder to start again.

About 5 minutes after the verification completes, the result is cleared. After that, a query returns 410. You cannot get the result back. Create a new verification request. If you poll at the interval that the previous section recommends, you usually get the result before it is cleared.

What you see when you verify after revocation

Section titled “What you see when you verify after revocation”

The wallet does not let the holder present a revoked credential. One of two things occurs: either the status stays pending (waiting) for the full timeout that you set, or the holder presents another credential of the same credential type, and the verification passes (verify_result: true). Check that data[].cid equals the credential_serial that you stored after issuance. Also set a timeout, as for any verification. For details, see Revoke API.

502 means that this request did not complete normally. The cause is on the TCS side, not in your request content. If TCS does not complete the request within 5 seconds, it also returns 502.

502 does not mean that the operation did not occur. Whether you can resend depends on the API:

APIWhen you get 502
Create issuance POST /v1/diw/issuancesDo not resend automatically. The issuance may already exist. Record the request time and the x-correlation-id / x-request-id value, and contact the TCS team.
Query issuance GET /v1/diw/issuances/{id}You can resend.
Create verification POST /v1/diw/verificationsYou can resend. The resend gives a new id. Use the new QR code.
Query verification GET /v1/diw/verifications/{id}You can resend.
Revoke POST /v1/diw/credentials/{cid}/revokeYou can resend. If the resend gets 400 and the message starts with issuer module 30205, the first revocation already succeeded. See Revoke API.

When you create an issuance, handle an HTTP client timeout, a broken connection, or no response in the same way as 502. Do not resend automatically. If your HTTP client, SDK, or API gateway automatically resends a request after it fails, turn off these automatic resends for the API that creates issuances. This prevents the same issuance from being created twice.

If you get another 5xx (for example 500, 503, or 504), handle it in the same way as 502.

A 502 response body is sometimes plain text, not JSON (for example error code: 502). In this case, the response has no correlationId. Write your x-correlation-id to your log before you send the request.

  • 401: usually the API Key has a problem. The message tells you which problem. Authentication failed is the exception: an error occurred on the TCS side when TCS checked the key. If your key is correct and this error continues, contact the TCS team with the request time and the x-correlation-id. For the table of messages, see API Basics.
  • 404 with a message of ... not found: this id belongs to a different account, or it was changed. When you query an issuance, it may also mean that the issuance does not exist. Check that you send the full id that you got when you created the request.

Send x-correlation-id and x-request-id with every request

Section titled “Send x-correlation-id and x-request-id with every request”

Send x-correlation-id with every request, and put the same value in x-request-id. For how to use it, see API Basics.

When the API rejects the request content, it returns 400. When you create a verification, the message format is verifier module <code>: <description>. When you create an issuance, the format is issuer module <code>: <description>. You can correct the error codes below in your own request. 10102 occurs when you create a verification (POST /v1/diw/verifications). All other codes occur when you create an issuance (POST /v1/diw/issuances):

Error codeMeaningHow to correct it
10102The verification scenario is not found (查無模板資料)Check that ref is exactly the same as the code that the TCS team gave you.
10108The credential type is not found (查無模板資料)Check that vc_uid is exactly the same as the code that the TCS team gave you.
11007This credential type is no longer issued (VC 模版已停止發行)Contact the TCS team to confirm which vc_uid you can use now.
11001A required field is missing, or its value is an empty string. An incomplete vc_uid also gets this codePut all required fields in fields, each with a value. Use the full vc_uid that the TCS team gave you. If an optional field has no value, you can leave it out or send an empty string.
10112The request contains a field that the credential type does not defineRemove the extra ename, or check the spelling.
10110A field value does not match the rules of its fieldCheck each content against the rules of its field. The message does not say which field is wrong, but it names the rule that failed, for example 只能輸入中英文數字和_.
10109A date is not a valid YYYYMMDD (for example 20261340)Check the format of issuance_date and expired_date.
10113issuance_date is a future dateChange it to today or an earlier date, or do not send this field.
10114expired_date is earlier than today, or earlier than the creation date of the credential typeChange it to a later date.

The description text in the message is passed on to you unchanged. It can be in Chinese or English. For error codes that are not in the table, contact the TCS team with the request time and the x-correlation-id.

Status codeMeaningWhat you do
201Created. Returns id, qrcode_image, deep_link, and warnings.Show the QR code and start polling.
400A field format is not correct (not an array, a value that is not a string, a date that is not 8 digits, extra fields, or a cid in cids that is not the full value). Or the request was rejected (the message starts with issuer module).Correct the request as the error message tells you. For error codes, see the table above.
401The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed).See API Basics.
404credential not found: cids contains a cid that does not belong to your account.Check cids.
502 or no responseThe request did not complete normally. The issuance may already exist.Do not resend automatically. Contact the TCS team with the request time and the x-correlation-id / x-request-id value.
Status codeMeaningWhat you do
200 pendingThe recipient has not accepted the credential.Query again after 2 to 5 seconds.
200 issuedThe recipient accepted the credential. Returns credential, cid, and credential_serial.Store the cid and the credential_serial.
400The id format is not correct (id is not an issuance id), or the request was rejected (the message starts with issuer module).Check that you send the full id that you got when you created the issuance.
401The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed).See API Basics.
404issuance not found: the id does not exist, does not belong to your account, or was changed.Check the id.
502The TCS side did not complete the request normally.You can resend.

Create verification POST /v1/diw/verifications

Section titled “Create verification POST /v1/diw/verifications”
Status codeMeaningWhat you do
201Created. Returns id, qrcode_image, and auth_uri.Show the QR code and start polling.
400ref is missing, empty, or not a string. Or the body has extra fields. Or the verification scenario does not accept this request (the message starts with verifier module).Check ref, and check that the body contains ref only.
401The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed).See API Basics.
502The TCS side did not complete the request normally.You can resend.

Query verification GET /v1/diw/verifications/{id}

Section titled “Query verification GET /v1/diw/verifications/{id}”
Status codeMeaningWhat you do
200 pendingThe holder has not completed.Query again after 2 to 5 seconds.
200 completedThe result is available.Read verify_result. For a credential that you issued, compare data[].cid. For the method, see Verification API. For a credential that another organization issued, use verify_result, credential_type, and claims to decide.
400The id format is not correct (id is not a verification id), or the request was rejected (the message starts with verifier module).Check that you send the full id that you got when you created the verification.
401The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed).See API Basics.
404verification not found: the id does not belong to your account, or it was changed.Check the id.
410The result is cleared.Create a new verification request.
502The TCS side did not complete the request normally.You can resend.

Revoke POST /v1/diw/credentials/{cid}/revoke

Section titled “Revoke POST /v1/diw/credentials/{cid}/revoke”
Status codeMeaningWhat you do
201Revoked. Returns cid and credential_status: REVOKED.Update your records.
400The cid format is not correct (cid is not a credential id), or the API rejected this revocation (the message starts with issuer module), for example because this credential is already revoked (issuer module 30205).If you got it after a resend, see Revoke API. In other cases: if the cid format is not correct, check the cid. If the message starts with issuer module, contact the TCS team with the request time and the x-correlation-id.
401The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed).See API Basics.
404credential not found: the cid does not belong to your account, or it was changed.Check the cid.
502The TCS side did not complete the request normally. The revocation may already be complete.You can resend.