Error Handling

The EduCare API uses conventional HTTP response codes to indicate the success or failure of API requests. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error with the provided information. Codes in the 5xx range indicate a server error.

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "status": 400,
  "details": {
    "field": "additional context"
  }
}

HTTP Status Codes

Status	Description
`200`	OK - Request succeeded
`201`	Created - Resource created successfully
`204`	No Content - Resource deleted successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Error Examples

Authentication Error

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

Validation Error

{
  "error": "Validation failed: email is required",
  "code": "VALIDATION_ERROR",
  "status": 400,
  "details": {
    "field": "email",
    "message": "Email is required"
  }
}

Resource Not Found

{
  "error": "Student not found",
  "code": "NOT_FOUND",
  "status": 404,
  "details": {
    "resource": "student",
    "id": 9999
  }
}

Rate Limiting

{
  "error": "Rate limit exceeded. Please wait before making more requests.",
  "code": "RATE_LIMITED",
  "status": 429,
  "details": {
    "retry_after": 60
  }
}

Handling Errors Example

Tip: Always check the status field to determine the type of error, then use the code field for programmatic handling.

async function fetchStudents() {
  try {
    const response = await fetch('https://api.educare.com/v1/students', {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (error.code) {
        case 'UNAUTHORIZED':
          // Redirect to login or refresh token
          break;
        case 'RATE_LIMITED':
          // Wait and retry
          await new Promise(r => setTimeout(r, error.details.retry_after * 1000));
          return fetchStudents();
        case 'NOT_FOUND':
          // Handle missing resource
          break;
        default:
          console.error('API Error:', error.message);
      }
    }
    
    return response.json();
  } catch (err) {
    console.error('Network error:', err);
  }
}

Best Practices

Always handle errors gracefully - Don't let API errors crash your application
Implement retry logic - For 429 and 5xx errors with exponential backoff
Log errors for debugging - Include the full error response for troubleshooting
Show user-friendly messages - Use the error field for display, code for logic

Error Handling

On this page