Error Codes

The 0.link API uses conventional HTTP status codes and provides error information to help you diagnose and resolve issues quickly.

Error Response Format

All error responses follow this structure:

{
  "error": "error_code",
  "message": "Human-readable error description"
}

Example:

{
  "error": "unauthorized",
  "message": "Missing bearer token. Provide 'Authorization: Bearer <token>' or '?token='."
}

HTTP Status Codes

Status	Description
401	Unauthorized - Missing or invalid authentication
422	Unprocessable Entity - Invalid request body or validation errors
500	Internal Server Error - Server-side error
502	Bad Gateway - Upstream service failure (e.g., OAuth introspection)

Error Codes

unauthorized (401)

Missing or invalid authentication token.

{
  "error": "unauthorized",
  "message": "Missing bearer token. Provide 'Authorization: Bearer <token>' or '?token='."
}

Common Causes:

• Missing Authorization header
• Missing Bearer prefix in token
• Invalid or expired API key
• Revoked API key

Solution: Include a valid API key in the Authorization header using the Bearer format.

introspection_failed (502)

OAuth token introspection failed. This occurs when verifying OAuth tokens with the identity provider.

{
  "error": "introspection_failed",
  "message": "Failed to introspect OAuth token"
}

Solution: Retry the request. If the issue persists, the identity provider may be experiencing issues.

invalid_body (422)

Invalid request body or JSON parsing error.

{
  "error": "invalid_body",
  "message": "Invalid JSON in request body"
}

Common Causes:

• Malformed JSON syntax
• Missing required fields
• Invalid field types

Solution: Verify your request body is valid JSON and matches the expected schema.

server_error (500)

Unexpected server-side error.

{
  "error": "server_error",
  "message": "An unexpected error occurred"
}

Solution: Retry the request. If the issue persists, contact support.

db_error (500)

Database operation failed.

{
  "error": "db_error",
  "message": "Database operation failed"
}

Solution: Retry the request. This is typically a transient error.

Handling Errors in Code

JavaScript Example

try {
  const response = await fetch('https://api.0.link/api/domains', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  if (!response.ok) {
    const error = await response.json();
    switch (error.error) {
      case 'unauthorized':
        console.log('Authentication failed:', error.message);
        break;
      case 'invalid_body':
        console.log('Invalid request:', error.message);
        break;
      default:
        console.error('API error:', error);
    }
  }
} catch (err) {
  console.error('Network error:', err);
}

Python Example

import requests

response = requests.get(
    'https://api.0.link/api/domains',
    headers={'Authorization': f'Bearer {api_key}'}
)

if not response.ok:
    error = response.json()
    if error.get('error') == 'unauthorized':
        print(f"Authentication failed: {error.get('message')}")
    elif error.get('error') == 'invalid_body':
        print(f"Invalid request: {error.get('message')}")
    else:
        print(f"API error: {error}")

Best Practices

Error Handling Strategy

1. Check HTTP status codes first - Use status codes for quick error categorization
2. Parse the error response - Extract error and message fields for details
3. Handle specific error codes - Implement handlers for expected errors
4. Log errors for debugging - Include the full error response in logs
5. Implement retry logic - For transient errors (500, 502), retry with backoff

Retry Logic

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fn();
      if (response.ok) return response;

      const error = await response.json();
      // Only retry on server errors
      if (response.status >= 500 && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
        continue;
      }
      throw error;
    } catch (err) {
      if (i === maxRetries - 1) throw err;
    }
  }
}

Getting Help

If you encounter unexpected errors:

• Contact Support: [email protected]
• Include: The error code, message, and request details