Error Codes

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

Error Response Format

All error responses follow this consistent structure:

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": "Additional context about the error",
    "field": "specific_field_name",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "api_version": "v2"
  }
}

HTTP Status Codes

Status	Code	Description
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Authentication Errors (401)

UNAUTHORIZED

Invalid or missing API key

{
  "code": "UNAUTHORIZED",
  "message": "Authentication required",
  "details": "No valid API key provided"
}

Solution: Include valid API key in Authorization header

INVALID_API_KEY

API key format is incorrect or key has been deleted

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid",
  "details": "Please check your API key and try again"
}

Solution: Verify API key in dashboard and regenerate if needed

Permission Errors (403)

INSUFFICIENT_PERMISSIONS

API key lacks required permissions

{
  "code": "INSUFFICIENT_PERMISSIONS",
  "message": "Your API key doesn't have write permissions",
  "required_permission": "write",
  "current_permissions": ["read"]
}

Solution: Update API key permissions or use a different key

PLAN_UPGRADE_REQUIRED

Feature requires higher plan

{
  "code": "PLAN_UPGRADE_REQUIRED",
  "message": "This feature requires a Pro plan",
  "feature": "advanced_analytics",
  "current_plan": "free"
}

Solution: Upgrade account plan or use alternative features

Validation Errors (422)

VALIDATION_ERROR

Request data failed validation

{
  "code": "VALIDATION_ERROR",
  "message": "The request contains invalid parameters",
  "details": "Name must be between 1 and 100 characters",
  "field": "name"
}

REQUIRED_FIELD_MISSING

Required parameter not provided

{
  "code": "REQUIRED_FIELD_MISSING",
  "message": "Required field is missing",
  "field": "name",
  "details": "The 'name' field is required for this operation"
}

Rate Limiting Errors (429)

RATE_LIMIT_EXCEEDED

Too many requests in time window

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retry_after": 60,
  "limit": 60,
  "window": "1 minute"
}

Solution: Implement exponential backoff and respect retry_after

Resource Errors (404)

RESOURCE_NOT_FOUND

Requested resource doesn't exist

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "The requested resource was not found",
  "resource_type": "project",
  "resource_id": "proj_123"
}

Server Errors (500)

INTERNAL_SERVER_ERROR

Unexpected server-side error

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred",
  "request_id": "req_abc123"
}

Solution: Retry request or contact support with request_id

Handling Errors in Code

JavaScript Example

try {
  const project = await client.projects.create(projectData);
} catch (error) {
  switch (error.code) {
    case 'VALIDATION_ERROR':
      console.log(`Validation failed: ${error.details}`);
      break;
    case 'INSUFFICIENT_PERMISSIONS':
      console.log('Need higher permissions');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      await sleep(error.retry_after * 1000);
      // Retry request
      break;
    default:
      console.error('Unexpected error:', error);
  }
}

Python Example

from zerolink.exceptions import (
    ValidationError,
    PermissionError,
    RateLimitError
)

try:
    project = client.projects.create(project_data)
except ValidationError as e:
    print(f"Validation failed: {e.details}")
except PermissionError as e:
    print(f"Permission denied: {e.message}")
except RateLimitError as e:
    time.sleep(e.retry_after)
    # Retry request

Best Practices

Error Handling Strategy

1. Always handle errors gracefully
2. Use error codes for programmatic handling
3. Display user-friendly messages
4. Log detailed errors for debugging
5. Implement retry logic for transient errors

Retry Logic

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
        await sleep(error.retry_after * 1000);
        continue;
      }
      throw error;
    }
  }
}

Getting Help

If you encounter unexpected errors:

• Check Status Page: status.0link.com
• Contact Support: support@0link.com
• Include Request ID: Always include the request_id from error responses