/** * Script to generate error documentation from OpenAPI specifications. * * The generated documentation is organized by HTTP status code and error type, * with up to MAX_EXAMPLES unique examples per error type. * * @usage node generate-openapi-error-page.js * @example node generate-openapi-error-page.js cdp-api-v2 */ const path = require("path"); const fs = require("fs"); const yaml = require("js-yaml"); const baseUrl = "https://docs.cdp.coinbase.com/"; const specId = process.argv[2]; const openApiSpecs = [ { id: "cdp-api-v2", name: "CDP API V2", specPath: path.join(__dirname, "../api-reference/v2/cdp-api-v2.yaml"), outputPath: path.join(__dirname, "../api-reference/v2/errors.mdx"), }, ]; // Add validation for spec-id if (!specId) { console.error("Error: No spec-id provided"); console.error("Usage: node generate-openapi-error-page.js "); process.exit(1); } const matchingSpec = openApiSpecs.find((spec) => spec.id === specId); if (!matchingSpec) { console.error(`Error: Invalid spec-id "${specId}"`); console.error( "Available spec-ids:", openApiSpecs.map((s) => s.id).join(", "), ); process.exit(1); } /** * Resolves a reference in the OpenAPI spec * @param {string} ref - The reference path (e.g. '#/components/responses/IdempotencyError') * @param {Object} spec - The full OpenAPI specification * @returns {Object} The resolved reference object */ function resolveRef(ref, spec) { const refParts = ref.replace("#/", "").split("/"); return refParts.reduce((obj, key) => obj[key], spec); } /** * Gets the complete example by combining schema defaults with provided example * @param {Object} schema - The error schema definition * @param {Object} spec - The full OpenAPI specification for resolving refs * @param {Object} example - The provided example values * @returns {Object} Complete example with all schema fields */ function getCompleteExample(schema, spec, example = {}) { // If no example was provided, return null to skip this error if (Object.keys(example).length === 0) { return null; } // If schema is a reference, resolve it if (schema.$ref) { schema = resolveRef(schema.$ref, spec); } const complete = { ...example }; // Add any missing required fields from schema if (schema.properties) { Object.entries(schema.properties).forEach(([field, prop]) => { if (!(field in complete)) { // If property is a reference, resolve it const resolvedProp = prop.$ref ? resolveRef(prop.$ref, spec) : prop; // Use example from property definition if available if (resolvedProp.example) { complete[field] = resolvedProp.example; } else if (resolvedProp.default) { complete[field] = resolvedProp.default; } else { // Use a descriptive placeholder for missing fields complete[field] = `<${field}>`; } } }); // Add errorLink after all other properties are set const errorType = complete.errorType || "error-type"; complete.errorLink = `${baseUrl}api-reference/v2/errors#${errorType}`; } return complete; } /** * Extracts error responses from an OpenAPI path object * @param {Object} pathObj - The OpenAPI path object containing response definitions * @param {Object} spec - The full OpenAPI specification for resolving refs * @returns {Array} Array of error objects with status, description and schema */ function extractErrorResponses(pathObj, spec) { const errors = []; // Look through each method (GET, POST, etc) Object.values(pathObj).forEach((method) => { if (!method.responses) return; // Look for error responses (4xx, 5xx) Object.entries(method.responses).forEach(([status, response]) => { if (!status.startsWith("4") && !status.startsWith("5")) return; // Resolve reference if present const resolvedResponse = response.$ref ? resolveRef(response.$ref, spec) : response; // Only process if there's a JSON schema if (resolvedResponse?.content?.["application/json"]?.schema) { const { schema } = resolvedResponse.content["application/json"]; const resolvedSchema = schema.$ref ? resolveRef(schema.$ref, spec) : schema; // Handle both single example and multiple examples const examples = resolvedResponse.content["application/json"].examples || (resolvedResponse.content["application/json"].example ? { default: { value: resolvedResponse.content["application/json"].example, }, } : {}); // Process each example Object.entries(examples).forEach(([exampleName, exampleObj]) => { const completeExample = getCompleteExample( resolvedSchema, spec, exampleObj.value, ); // Skip if no complete example could be generated if (!completeExample) return; errors.push({ status, description: resolvedResponse.description, schema: resolvedSchema, example: completeExample, exampleName, // Include example name for multiple examples }); }); } }); }); return errors; } /** * Gets error instructions for a given error type * @param {string} errorType - The error type to get instructions for * @param {Object} spec - The full OpenAPI specification * @returns {string|null} The error instructions markdown if found, null otherwise */ function getErrorInstructions(errorType, spec) { // Look for instructions in the ErrorType schema const errorTypeSchema = spec.components.schemas.ErrorType; if (errorTypeSchema?.["x-error-instructions"]?.[errorType]) { return errorTypeSchema["x-error-instructions"][errorType]; } return null; } /** * Replaces absolute URLs that start with baseUrl with relative links in generated content * Keeps errorLink as an absolute URL * @param {string} content - The content to process * @returns {string} Content with absolute URLs replaced by relative links */ function replaceAbsoluteUrls(content) { if (!baseUrl) return content; // Skip URLs in JSON examples (errorLink should remain as absolute URL) const parts = []; let inCodeBlock = false; let currentPart = ""; content.split("\n").forEach((line) => { if (line.startsWith("```")) { inCodeBlock = !inCodeBlock; currentPart += `${line}\n`; if (!inCodeBlock) { // We've reached the end of a code block, add it without changes parts.push(currentPart); currentPart = ""; } } else if (inCodeBlock) { // Inside a code block, don't replace URLs currentPart += `${line}\n`; } else { // Regular markdown text, replace absolute URLs with relative ones // Use a regex to match URLs that start with baseUrl const regex = new RegExp(`${baseUrl}([^\\s")]+)`, "g"); const replacedLine = line.replace(regex, (match, urlPath) => { return `/${urlPath}`; }); currentPart += `${replacedLine}\n`; } }); // Add any remaining content if (currentPart) { parts.push(currentPart); } return parts.join(""); } /** * Generates markdown documentation for API errors * @param {Object} spec - The parsed OpenAPI specification * @returns {string} Markdown formatted error documentation */ function generateErrorDocs(spec) { let markdown = `--- title: Errors --- # API Errors The CDP API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: - Codes in the \`2xx\` range indicate success - Codes in the \`4xx\` range indicate an error that failed given the information provided (e.g., a required parameter was omitted) - Codes in the \`5xx\` range indicate an error on CDP's backend servers. \`5xx\` errors are not a guarantee of failure; there's always the chance that the operation may have succeeded in our back-end. Therefore, your application should treat the operation's status as **unknown**. Each error response includes: - \`errorType\`: A machine-readable error code - \`errorMessage\`: A human-readable message providing more detail - \`correlationId\`: A unique identifier for the request that can help with debugging - \`errorLink\`: A link to detailed documentation about the specific error type `; // Group errors by status code and error type const errorsByStatus = new Map(); const MAX_EXAMPLES = 3; Object.entries(spec.paths).forEach(([, pathObj]) => { const errors = extractErrorResponses(pathObj, spec); errors.forEach((error) => { if (!errorsByStatus.has(error.status)) { errorsByStatus.set(error.status, new Map()); } const errorTypeMap = errorsByStatus.get(error.status); const { example } = error; const errorType = example?.errorType || "unknown"; // Store all examples for this error type if (!errorTypeMap.has(errorType)) { errorTypeMap.set(errorType, { description: error.description, examples: [], instructions: getErrorInstructions(errorType, spec), }); } // Add this example if it's unique and we haven't hit the limit const errorInfo = errorTypeMap.get(errorType); const isDuplicate = errorInfo.examples.some( (e) => JSON.stringify(e) === JSON.stringify(example), ); if (!isDuplicate && errorInfo.examples.length < MAX_EXAMPLES) { errorInfo.examples.push(example); } }); }); // Sort by status code const sortedStatuses = Array.from(errorsByStatus.keys()).sort(); // Generate documentation for each status code and its error types sortedStatuses.forEach((status) => { markdown += `## HTTP ${status}\n\n`; const errorTypeMap = errorsByStatus.get(status); const errorTypes = Array.from(errorTypeMap.entries()); errorTypes.forEach(([errorType, error]) => { markdown += `### ${errorType}\n\n`; // Add error instructions if they exist if (error.instructions) { markdown += `${error.instructions}\n\n`; } // Add up to MAX_EXAMPLES examples for this error type error.examples.forEach((example, index) => { if (error.examples.length > 1) { markdown += `**Example ${index + 1}:**\n\n`; } else { markdown += `**Example error response:**\n\n`; } markdown += `\`\`\`json lines wrap\n${JSON.stringify(example, null, 2)}\n\`\`\`\n\n`; }); }); }); markdown += ` ## Network Errors Network errors occur when there is a problem establishing or maintaining a connection to the CDP API at the network layer. These errors are distinct from API service errors - they indicate that your request never reached the CDP API or was blocked before it could be processed. ### Understanding Network Errors When you encounter a network error via the CDP SDK, you'll receive a \`NetworkError\` object with: - \`statusCode\`: Always 0 (indicating no HTTP response was received) - \`errorType\`: Specific type of network error - \`errorMessage\`: Human-readable description - \`networkDetails\`: Additional information including: - \`code\`: Technical error code - \`message\`: Original error message - \`retryable\`: Whether the operation should be retried ### Types of Network Errors #### 1. **IP Blocked** (\`network_ip_blocked\`) Your IP address has been blocked at the gateway level. **Common causes:** - Geographic restrictions. - Rate limiting at infrastructure level. - Security policies or DDoS protection. - Corporate firewall/proxy restrictions. **What to do:** - Verify you're not accessing from a [restricted region](https://help.coinbase.com/en/coinbase/managing-my-account/other/prohibited-regions). - Check if you're behind a VPN or proxy that might be blocked. - Contact [CDP support on Discord](https://discord.com/channels/1220414409550336183/1271495764580896789) if you believe this is in error. - This error is **not retryable**. #### 2. **Connection Failed** (\`network_connection_failed\`) Unable to establish a connection to the CDP API. **Common causes:** - CDP API is temporarily unavailable. Check the [CDP Status Page](https://cdpstatus.coinbase.com/#status) for any ongoing issues. - Network connectivity issues. - Firewall blocking outbound HTTPS connections. - Incorrect API endpoint configuration. **What to do:** - Check your internet connection. - Verify firewall settings allow HTTPS traffic to \`api.cdp.coinbase.com\`. - Ensure you're using the correct API endpoint. - This error is **retryable**. Retry the request with [exponential backoff](/api-reference/v2/errors#handling-network-errors-in-code). #### 3. **Timeout** (\`network_timeout\`) The request took too long and was terminated. **Common causes:** - Network congestion. - Slow internet connection. **What to do:** - Increase timeout settings if consistently timing out. - This error is **retryable**. Retry the request with [exponential backoff](/api-reference/v2/errors#handling-network-errors-in-code). #### 4. **DNS Failure** (\`network_dns_failure\`) Unable to resolve the CDP API domain name. **Common causes:** - DNS configuration issues. - Network connectivity problems. - DNS server unavailable. - Incorrect API endpoint URL. **What to do:** - Check your DNS settings. - Verify network connectivity with \`nslookup api.cdp.coinbase.com\`. - Try using a different DNS server (e.g., 8.8.8.8). - Ensure the API URL is correct. - This error is **not retryable** until DNS is fixed. ### Handling Network Errors in Code \`\`\`typescript main.ts lines wrap import { NetworkError } from '@coinbase/cdp-sdk'; try { const account = await cdp.evm.getAccount({ address: '0x...' }); } catch (error) { if (error instanceof NetworkError) { console.error(\`Network error: \` + error.errorMessage); console.error(\`Type: \` + error.errorType); console.error(\`Details:\` + error.networkDetails); // Check if the error is retryable if (error.networkDetails?.retryable) { // Implement retry logic with exponential backoff await retryWithBackoff(async () => { return await cdp.evm.getAccount({ address: '0x...' }); }); } else { // Handle non-retryable errors if (error.errorType === "network_ip_blocked") { console.error('Your IP appears to be blocked. Please check your network configuration.'); } } } } \`\`\` \`\`\`python main.py lines wrap from cdp import CdpClient, NetworkError, HttpErrorType import time cdp = CdpClient() try: account = await cdp.evm.get_account(address="0x...") except NetworkError as e: print(f"Network error: {e.error_message}") print(f"Type: {e.error_type}") print(f"Details: {e.network_details}") # Check if the error is retryable if e.network_details.get("retryable", False): # Implement retry logic with exponential backoff retry_with_backoff(lambda: cdp.evm.get_account(address="0x...")) else: # Handle non-retryable errors if e.error_type == HttpErrorType.NETWORK_IP_BLOCKED: print("Your IP appears to be blocked. Please check your network configuration.") \`\`\` ### Best Practices 1. **Implement Retry Logic**: For retryable errors, use exponential backoff: \`\`\`typescript retry-with-backoff.ts lines wrap async function retryWithBackoff( fn: () => Promise, maxRetries = 3, baseDelay = 1000 ): Promise { for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (error) { if (error instanceof NetworkError && error.networkDetails?.retryable && i < maxRetries - 1) { await new Promise(resolve => setTimeout(resolve, baseDelay * Math.pow(2, i))); continue; } throw error; } } throw new Error('Max retries exceeded'); } \`\`\` \`\`\`python retry-with-backoff.py lines wrap def retry_with_backoff(fn, max_retries=3, base_delay=1000): for attempt in range(max_retries): try: return await fn() except Exception as e: if isinstance(e, NetworkError) and e.network_details.get("retryable", False) and attempt < max_retries - 1: await asyncio.sleep(base_delay * 2 ** attempt) continue raise e \`\`\` 2. **Log Network Errors**: Always log network errors with full details for debugging. 3. **Monitor Patterns**: Track network errors to identify patterns (time of day, specific operations, etc.). 4. **Have Fallback Strategies**: Consider implementing fallback mechanisms for critical operations. ### Troubleshooting Checklist - Verify internet connectivity. - Check if you're behind a proxy or VPN. - Ensure firewall allows HTTPS traffic to \`api.cdp.coinbase.com\`. - Verify you're not in a restricted geographic region. - Check DNS resolution: \`nslookup api.cdp.coinbase.com\`. - Test with \`curl\` or similar: \`curl -I https://api.cdp.coinbase.com/platform\`. - Check if the issue is consistent or intermittent. ### Getting Help If you continue to experience network errors after following this guide: 1. Collect error details including: - Full error message and type. - Network details from the error. - Time and frequency of occurrence. - Your network configuration (proxy, VPN, region). 2. Contact [CDP support on Discord](https://discord.com/channels/1220414409550336183/1271495764580896789) with this information. 3. Check the [CDP Status Page](https://cdpstatus.coinbase.com/#status) for any ongoing issues. Remember: Network errors are typically environmental issues rather than code problems. Focus on network configuration and connectivity when troubleshooting. `; return markdown; } openApiSpecs.forEach((spec) => { if (spec.id !== specId) { return; } console.log(`Reading ${spec.name} OpenAPI spec...`); try { // Read and parse YAML file const fileContents = fs.readFileSync(spec.specPath, "utf8"); const openApiSpec = yaml.load(fileContents); // Generate error documentation const errorDocs = generateErrorDocs(openApiSpec); // Process the content to replace absolute URLs with relative links // This doesn't affect errorLink in JSON examples which will remain absolute const processedDocs = replaceAbsoluteUrls(errorDocs); // Write to output file fs.writeFileSync(spec.outputPath, processedDocs); console.log(`Generated error documentation at ${spec.outputPath}`); } catch (error) { console.error("Error processing OpenAPI spec:", error); process.exit(1); } });

GET STARTED

WALLETS

PAYMENTS

SWAPS

BASE TOOLS

DATA

AI

STAKING

FAUCET

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

​2025

​2025-JUN-30

2025

2025-JUN-30