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.
Polling stays pending
Section titled “Polling stays pending”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.
Verification result expired (410)
Section titled “Verification result expired (410)”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.
You get 502
Section titled “You get 502”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:
| API | When you get 502 |
|---|---|
Create issuance POST /v1/diw/issuances | Do 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/verifications | You 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}/revoke | You 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 and 404
Section titled “401 and 404”401: usually the API Key has a problem. Themessagetells you which problem.Authentication failedis 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 thex-correlation-id. For the table of messages, see API Basics.404with amessageof... 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.
Error codes that you can correct yourself
Section titled “Error codes that you can correct yourself”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 code | Meaning | How to correct it |
|---|---|---|
10102 | The verification scenario is not found (查無模板資料) | Check that ref is exactly the same as the code that the TCS team gave you. |
10108 | The credential type is not found (查無模板資料) | Check that vc_uid is exactly the same as the code that the TCS team gave you. |
11007 | This credential type is no longer issued (VC 模版已停止發行) | Contact the TCS team to confirm which vc_uid you can use now. |
11001 | A required field is missing, or its value is an empty string. An incomplete vc_uid also gets this code | Put 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. |
10112 | The request contains a field that the credential type does not define | Remove the extra ename, or check the spelling. |
10110 | A field value does not match the rules of its field | Check 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 只能輸入中英文數字和_. |
10109 | A date is not a valid YYYYMMDD (for example 20261340) | Check the format of issuance_date and expired_date. |
10113 | issuance_date is a future date | Change it to today or an earlier date, or do not send this field. |
10114 | expired_date is earlier than today, or earlier than the creation date of the credential type | Change 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.
Full status code tables
Section titled “Full status code tables”Create issuance POST /v1/diw/issuances
Section titled “Create issuance POST /v1/diw/issuances”| Status code | Meaning | What you do |
|---|---|---|
201 | Created. Returns id, qrcode_image, deep_link, and warnings. | Show the QR code and start polling. |
400 | A 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. |
401 | The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed). | See API Basics. |
404 | credential not found: cids contains a cid that does not belong to your account. | Check cids. |
502 or no response | The 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. |
Query issuance GET /v1/diw/issuances/{id}
Section titled “Query issuance GET /v1/diw/issuances/{id}”| Status code | Meaning | What you do |
|---|---|---|
200 pending | The recipient has not accepted the credential. | Query again after 2 to 5 seconds. |
200 issued | The recipient accepted the credential. Returns credential, cid, and credential_serial. | Store the cid and the credential_serial. |
400 | The 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. |
401 | The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed). | See API Basics. |
404 | issuance not found: the id does not exist, does not belong to your account, or was changed. | Check the id. |
502 | The 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 code | Meaning | What you do |
|---|---|---|
201 | Created. Returns id, qrcode_image, and auth_uri. | Show the QR code and start polling. |
400 | ref 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. |
401 | The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed). | See API Basics. |
502 | The 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 code | Meaning | What you do |
|---|---|---|
200 pending | The holder has not completed. | Query again after 2 to 5 seconds. |
200 completed | The 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. |
400 | The 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. |
401 | The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed). | See API Basics. |
404 | verification not found: the id does not belong to your account, or it was changed. | Check the id. |
410 | The result is cleared. | Create a new verification request. |
502 | The 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 code | Meaning | What you do |
|---|---|---|
201 | Revoked. Returns cid and credential_status: REVOKED. | Update your records. |
400 | The 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. |
401 | The API Key has a problem, or an error occurred on the TCS side when TCS checked the key (Authentication failed). | See API Basics. |
404 | credential not found: the cid does not belong to your account, or it was changed. | Check the cid. |
502 | The TCS side did not complete the request normally. The revocation may already be complete. | You can resend. |