Error Handling

Error Response Format

All API errors follow a standard envelope:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "errors": {
      "field_name": ["validation message"]
    }
  }
}

Field	Type	Always present?	Description
`success`	boolean	✅	Always `false` for errors
`error.code`	string	✅	Machine-readable code (use for switch/case)
`error.message`	string	✅	Human-readable description
`error.errors`	object	❌ Only on 422	Field-level validation errors

Handling in Dart

class ApiError {
  final String code;
  final String message;
  final Map<String, List<String>>? fieldErrors;

  factory ApiError.fromJson(Map<String, dynamic> json) {
    final error = json['error'];
    return ApiError(
      code: error['code'],
      message: error['message'],
      fieldErrors: error['errors']?.map(
        (k, v) => MapEntry(k, List<String>.from(v)),
      ),
    );
  }
}

// Usage
if (response.statusCode != 200) {
  final error = ApiError.fromJson(jsonDecode(response.body));
  switch (error.code) {
    case 'VALIDATION_ERROR':
      showFieldErrors(error.fieldErrors!);
      break;
    case 'UNAUTHORIZED':
      await refreshTokenOrLogout();
      break;
    case 'PAYMENT_REQUIRED':
      navigateToPayFees();
      break;
    default:
      showGenericError(error.message);
  }
}

Error Code Reference

Code	HTTP Status	When	Frontend Action
`UNAUTHORIZED`	401	Missing/invalid/expired JWT	Refresh token or redirect to login
`FORBIDDEN`	403	Insufficient role permissions	Show “Access denied”
`ROLE_CONFLICT`	403	User exists with different role	Show “Already registered as “
`NOT_FOUND`	404	Resource doesn’t exist	Show 404 screen
`CONFLICT`	409	Job already taken by another mechanic	Dismiss offer, show “Already taken”
`INVALID_TRANSITION`	409	Invalid job status change	Refresh job status from API
`VALIDATION_ERROR`	422	Request body fails Zod validation	Highlight invalid form fields
`RATING_WINDOW_EXPIRED`	422	Rating submitted after 7-day window	Show “Rating period expired”
`PAYMENT_REQUIRED`	402	Unpaid cancellation fees	Redirect to pay fees
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Show “Try again in X seconds”
`INTERNAL_ERROR`	500	Server error	Show generic error, retry later

Rate Limiting

The API enforces rate limits at multiple levels. When exceeded, you’ll receive a 429 response.

Limits

Scope	Limit	Applied to
Global	60 requests/minute per IP	All endpoints
Auth	10 requests/minute per IP	`/auth/verify-otp` only
Tracking HTTP	1 request/2 seconds	`GET /tracking/jobs/{id}`
Admin invite	Stricter limit	`/auth/complete-admin-invite`

Socket.io Event Limits

Event	Limit
`location:update`	60/minute
`job:join`	10/minute
`job:leave`	10/minute

Response Headers

Every response includes rate limit info:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1716300060

Header	Description
`X-RateLimit-Limit`	Max requests in the window
`X-RateLimit-Remaining`	Requests left in current window
`X-RateLimit-Reset`	Unix timestamp when window resets

Handling 429 in Dart

if (response.statusCode == 429) {
  final resetAt = int.parse(response.headers['x-ratelimit-reset'] ?? '0');
  final waitSeconds = resetAt - DateTime.now().millisecondsSinceEpoch ~/ 1000;
  await Future.delayed(Duration(seconds: waitSeconds));
  // Retry the request
}

Pagination

Paginated endpoints accept page and limit query parameters and return a standard envelope:

GET /api/v1/jobs?page=2&limit=10&status=completed

Response:

{
  "data": [
    { "id": "...", "status": "completed", ... },
    { "id": "...", "status": "completed", ... }
  ],
  "page": 2,
  "limit": 10,
  "total": 42
}

Field	Type	Description
`data`	array	The items for the current page
`page`	number	Current page (1-indexed)
`limit`	number	Items per page (default 20)
`total`	number	Total items matching the query

Paginated Endpoints

GET /api/v1/jobs — filter by status
GET /api/v1/notifications — user notifications
GET /api/v1/admin/users — filter by role
GET /api/v1/admin/mechanics — mechanic list
GET /api/v1/admin/jobs — filter by status
GET /api/v1/ratings/mechanic/{id} — mechanic ratings

Dart Helper

class PaginatedResponse<T> {
  final List<T> data;
  final int page;
  final int limit;
  final int total;

  int get totalPages => (total / limit).ceil();
  bool get hasNextPage => page < totalPages;
  bool get hasPreviousPage => page > 1;
}

Validation Errors (422)

When request validation fails (Zod), the errors field contains field-level details:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "errors": {
      "pickup_lat": ["Number must be between -90 and 90"],
      "pickup_lng": ["Number must be between -180 and 180"],
      "service_category_id": ["Required"]
    }
  }
}

Map these to form field errors in your UI:

if (error.code == 'VALIDATION_ERROR' && error.fieldErrors != null) {
  for (final entry in error.fieldErrors!.entries) {
    formKey.currentState?.fields[entry.key]?.invalidate(entry.value.first);
  }
}

Getting Started

Guides

Development

Error Response Format

Handling in Dart

Error Code Reference

Rate Limiting

Limits

Socket.io Event Limits

Response Headers

Handling 429 in Dart

Paginated Endpoints

Dart Helper

Validation Errors (422)

​Error Response Format

​Handling in Dart

​Error Code Reference

​Rate Limiting

​Limits

​Socket.io Event Limits

​Response Headers

​Handling 429 in Dart

​Pagination

​Paginated Endpoints

​Dart Helper

​Validation Errors (422)

Error Response Format

Handling in Dart

Error Code Reference

Rate Limiting

Limits

Socket.io Event Limits

Response Headers

Handling 429 in Dart

Pagination

Paginated Endpoints

Dart Helper

Validation Errors (422)