Troubleshooting

Testing a credential Test the services independently using the testers in the Vidos Dashboard to confirm they are operational.

1Error
2Request timed out. Please try again.

Error

resolverInstance API error

Validation

A DID (Decentralized Identifier) method follows the format:

1did:<method>:<method-specific-id>

To match a valid DID with any method name, use the following regex:

1^did:[a-z0-9]+:[a-zA-Z0-9._\\\\-:]+$

Explanation

• ^ asserts the start of the string.
• did: ensures the string starts with "did:".
• [a-z0-9]+ matches the method name (one or more lowercase letters or digits).
• : is the required separator.
• [a-zA-Z0-9._\\\\-:]+ matches the method-specific identifier (alphanumeric characters, dots, underscores, hyphens, and colons).
• $ asserts the end of the string.

Examples of valid DIDs:

• did:example:123456789abcdefghi
• did:key:z6MkfRLMVx7N6HQoGAw9C
• did:web:example.com:users:alice

This regex allows flexibility in the method-specific ID, supporting common characters used in DID schemes. #vidos-articles

Error

1{
2    "checks": [
3        "format",
4        "proof"
5    ],
6    "warnings": [],
7    "errors": [
8        "Failed to canonicalize"
9    ]
10}

Credential

1{
2    "verifiablePresentation": {
3        "id": "id:test",
4        "proof": {
5            "proofValue": "zkhFb45dDtvpxfu21fyAMxi4tqRnNKDSouckj24JG9AAKKa2wpoq9RUvACP6kmJmZUrjrP4GVvRLyFJQNhRDCgfS",
6            "created": "2023-03-01T21:29:24Z",
7            "proofPurpose": "assertionMethod",
8            "type": "DataIntegrityProof",
9            "verificationMethod": "did:key:zDnaekGZTbQBerwcehBSXLqAg6s55hVEBms1zFy89VHXtJSa9#zDnaekGZTbQBerwcehBSXLqAg6s55hVEBms1zFy89VHXtJSa9",
10            "cryptosuite": "ecdsa-rdfc-2019"
11        },
12        "type": [
13            "VerifiablePresentation"
14        ],
15        "@context": [
16            "https://www.w3.org/2018/credentials/v1",
17            "https://w3id.org/secusrity/data-integrity/v2"
18        ],
19        "verifiableCredential": [
20            {
21                "issuanceDate": "2010-01-01T19:23:24Z",
22                "credentialSubject": {
23                    "alumniOf": "Example University",
24                    "id": "https://example.edu/students/alice"
25                },
26                "id": "http://example.edu/credentials/1872",
27                "proof": {
28                    "proofValue": "zNqtAbEWenMxFDB8omdCSzY5S1GGNAQjWibDycCnJMkHeLF5apDje6QxSgqsjn5AMqDRkX7dsh9BnVpbAnnkzTX1",
29                    "created": "2023-03-01T21:29:24Z",
30                    "proofPurpose": "assertionMethod",
31                    "type": "DataIntegrityProof",
32                    "verificationMethod": "did:key:zDnaekGZTbQBerwcehBSXLqAg6s55hVEBms1zFy89VHXtJSa9#zDnaekGZTbQBerwcehBSXLqAg6s55hVEBms1zFy89VHXtJSa9",
33                    "cryptosuite": "ecdsa-rdfc-2019"
34                },
35                "type": [
36                    "VerifiableCredential",
37                    "AlumniCredential"
38                ],
39                "@context": [
40                    "https://www.w3.org/2018/credentials/v1",
41                    {
42                        "alumniOf": "https://schema.org#alumniOf",
43                        "AlumniCredential": "https://schema.org#AlumniCredential"
44                    },
45                    "https://w3id.org/security/data-integrity/v2"
46                ],
47                "issuer": "did:key:zDnaekGZTbQBerwcehBSXLqAg6s55hVEBms1zFy89VHXtJSa9"
48            }
49        ]
50    }
51}

Resolver Errors

Common Error Cases:

• Invalid did:key format
• Unsupported key type
• Network connectivity issues

Best Practices:

• Validate did:key format before resolution
• Add error handling for all failure cases
• Log resolution failures for monitoring

Vidos Connector Troubleshooting Guide

Quick Start

Before diving into specific errors, try these first steps:

• Test services independently using the testers in the Vidos Dashboard
• Verify your API keys have the correct permissions
• Check your network connectivity to Vidos services
• Validate your input format matches the examples in the documentation

Common Errors and Solutions

Request Timeouts

Error: Request timed out. Please try again.

Possible Causes:

• Network connectivity issues
• Service temporary unavailability

Solutions:

1. Check your network connection
2. Verify the service status in Vidos Dashboard
3. Consider implementing retry logic with exponential backoff

Resolver Instance API Errors

Possible Causes:

• Invalid API key
• Incorrect endpoint URL
• Missing permissions
• Rate limit exceeded

Solutions:

1. Verify API key in Vidos Dashboard
2. Check endpoint URL format
3. Review API key permissions
4. Monitor your API usage

DID Validation Errors

DIDs must follow the format: did:<method>:<method-specific-id>

Valid DID Format (Regex):

1^did:[a-z0-9]+:[a-zA-Z0-9._\\\\-:]+$

Example Valid DIDs:

• did:example:123456789abcdefghi
• did:key:z6MkfRLMVx7N6HQoGAw9C
• did:web:example.com:users:alice

Common DID Validation Issues:

• Missing 'did:' prefix
• Invalid method name
• Invalid characters in method-specific ID
• Uppercase letters in method name

Canonicalization Errors

1{
2    "checks": ["format", "proof"],
3    "warnings": [],
4    "errors": ["Failed to canonicalize"]
5}

Possible Causes:

• Malformed JSON-LD context
• Invalid or missing @context values
• Incorrect ordering of credential properties
• Typos in context URLs (e.g., "secusrity" instead of "security")

Solutions:

1. Verify all @context URLs are correct and accessible
2. Ensure credential properties follow the W3C VC data model
3. Check for typos in context URLs (e.g., fix "secusrity" to "security")
4. Validate JSON-LD structure before sending

Resolver-Specific Errors

did:key Resolution Issues

Common Error Cases:

• Invalid did:key format
• Unsupported key type
• Network connectivity issues

Best Practices:

• Validate did:key format before resolution
• Add error handling for all failure cases
• Log resolution failures for monitoring

Performance Optimization

Response Time Improvements

1. Implement caching where appropriate
2. Use batch operations when possible
3. Monitor and optimize payload sizes

Resource Usage

1. Implement proper connection pooling
2. Close connections properly
3. Handle cleanup of resources in error cases

Monitoring and Debugging

Logging Best Practices

1. Log all API requests and responses
2. Include correlation IDs
3. Track timing metrics
4. Log at appropriate levels (ERROR, WARN, INFO)

Metrics to Monitor

• API response times
• Error rates
• Success/failure ratios
• Rate limit usage

Testing Recommendations

Integration Testing

1. Test with sample credentials before production use
2. Validate error handling paths
3. Test with various credential types
4. Verify timeout handling

Load Testing

1. Test with expected production volumes
2. Verify rate limit handling
3. Test error scenarios under load
4. Monitor resource usage

Support Resources

• Vidos Dashboard: https://dashboard.vidos.id
• API Documentation: https://docs.vidos.id
• Support Email: support@vidos.id

Error Reference

HTTP Status Codes

• 400: Bad Request (invalid input)
• 401: Unauthorized (invalid API key)
• 403: Forbidden (insufficient permissions)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error (service issue)

Common Error Messages