Error Handling | docs.do.dev

Learn how to handle errors from the do.dev APIs.

Error Response Format

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "details": {}
  }
}

HTTP Status Codes

Code	Description
200	Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
429	Rate Limited
500	Internal Error

Error Codes

Authentication Errors

Code	Description
`unauthorized`	Missing or invalid auth
`token_expired`	Access token expired
`insufficient_scope`	Missing required scope

Validation Errors

Code	Description
`invalid_request`	Malformed request
`missing_field`	Required field missing
`invalid_field`	Invalid field value

Resource Errors

Code	Description
`not_found`	Resource doesn't exist
`already_exists`	Resource already exists
`conflict`	Resource conflict

Rate Limit Errors

Code	Description
`rate_limited`	Too many requests

Billing Errors

Code	Description
`subscription_required`	Paid subscription needed
`usage_exceeded`	Usage limit reached
`payment_failed`	Payment unsuccessful

Handling Errors

JavaScript/TypeScript

try {
  const response = await dodev.users.get('user_123');
} catch (error) {
  if (error.code === 'not_found') {
    console.log('User not found');
  } else if (error.code === 'rate_limited') {
    // Wait and retry
    await sleep(error.retryAfter * 1000);
    // Retry request
  } else {
    throw error;
  }
}

With Fetch

const response = await fetch('https://api.do.dev/v1/users/123', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});

if (!response.ok) {
  const error = await response.json();

  switch (error.error.code) {
    case 'unauthorized':
      // Handle auth error
      break;
    case 'rate_limited':
      // Handle rate limit
      break;
    default:
      throw new Error(error.error.message);
  }
}

Retry Strategy

For transient errors, implement exponential backoff:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || '1';
        await sleep(parseInt(retryAfter) * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

Getting Help

If you encounter unexpected errors:

Check the error code and message
Review the API documentation
Check the status page
Contact support with the request ID

On this page