Error Handling

Overview

The Juadah API uses a consistent error response format across all endpoints. Understanding this format will help you build robust error handling in your applications.

Error Response Format

All error responses follow this structure:

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "Human-readable error message",
    "details": {
      "field1": "Error description for field1",
      "field2": "Error description for field2"
    }
  }
}

Response Fields

status

string

required

Always "fail" for error responses. Success responses use "success".

errors

object

required

Container for error information.

Show errors properties

code

number

required

HTTP status code (400, 404, 500, etc.)

message

string

required

Human-readable error message describing what went wrong

details

object

Optional field-specific validation errors. Only present for validation errors.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the type of error:

400 - Bad Request

Invalid request due to validation errors or malformed data

404 - Not Found

The requested resource does not exist

500 - Internal Server Error

Something went wrong on the server side

Error Types

Validation Errors

Occur when request data doesn’t meet validation requirements. Example - Registration Validation Error:

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "validation error",
    "details": {
      "email": "invalid email format",
      "password": "password should have minimum 6 characters length"
    }
  }
}

Common Validation Errors:

Email Validation

From src/auth/schema.ts:4-6:

"email is required" - Email field is missing
"your email format is invalid" - Email format is incorrect

email: z
  .string({ required_error: 'email is required' })
  .email('your email format is invalid')
  .min(1, 'email is required')

Password Validation

From src/auth/schema.ts:8-10:

"password is required" - Password field is missing
"password and password confirmation is not match" - Passwords don’t match

password: z
  .string({ required_error: 'password is required' })
  .min(1, 'password is required')

Product Validation

"product name cannot be empty" - Name is required
"product price cannot be empty" - Price is required
"image extension is not supported" - Invalid file format
"each product can only have 5 images at max" - Too many images

Authentication Errors

Occur when authentication credentials are invalid or missing.

Invalid Credentials
Email Already Exists
Invalid Refresh Token

Error: Incorrect email or password during login

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "email or password is incorrect"
  }
}

Triggered by (src/lib/Error.ts:1-5):

export class AuthCredentialError extends Error {
  constructor(message = 'email or password is incorrect') {
    super(message)
  }
}

Error: Attempting to register with an existing email

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "this email already exists"
  }
}

Triggered by (src/lib/Error.ts:7-11):

export class EmailAlreadyExistsError extends Error {
  constructor(message = 'this email already exists') {
    super(message)
  }
}

Error: Refresh token is missing or invalid

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "invalid request, refresh token unavailable"
  }
}

Or:

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "invalid refresh token"
  }
}

Not Found Errors

Occur when a requested resource doesn’t exist.

{
  "status": "fail",
  "errors": {
    "code": 404,
    "message": "resource you're looking for is not found"
  }
}

Common scenarios:

Product ID doesn’t exist
Order ID not found
No products available

Implementation (src/lib/Error.ts:13-19):

export class NotFoundError extends Error {
  public code: number
  constructor(message: string) {
    super(message)
    this.code = 404
  }
}

Bad Request Errors

Occur when the request is malformed or contains invalid data.

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "Invalid request parameters"
  }
}

Implementation (src/lib/Error.ts:21-27):

export class BadRequestError extends Error {
  public code: number
  constructor(message: string) {
    super(message)
    this.code = 400
  }
}

Server Errors

Occur when something goes wrong on the server side.

{
  "status": "fail",
  "errors": {
    "code": 500,
    "message": "this is not your fault, something went wrong in our system, please try again later"
  }
}

Common scenarios:

Database connection failure
External service unavailable
Unexpected server errors

Implementation (src/lib/Error.ts:29-35):

export class ServerError extends Error {
  public code: number
  constructor(message: string) {
    super(message)
    this.code = 500
  }
}

Database Connection Error Example (from src/auth/service.ts:156-166):

{
  "status": "fail",
  "errors": {
    "code": 500,
    "message": "this is not your fault, something went wrong in our system, please try again later"
  }
}

Custom Validation Errors

Used for multipart form data validation (file uploads).

{
  "status": "fail",
  "errors": {
    "code": 400,
    "message": "validation error",
    "details": {
      "images": "invalid file format, please only upload file with .png or .jpg extension"
    }
  }
}

Implementation (src/lib/Error.ts:41-47):

export class CustomValidationError extends Error {
  public fieldname: string
  constructor(message: string, fieldname: string) {
    super(message)
    this.fieldname = fieldname
  }
}

Error Handling Examples

async function loginUser(email, password) {
  try {
    const response = await fetch('https://juadah-backend.vercel.app/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify({ email, password })
    });
    
    const data = await response.json();
    
    // Check response status
    if (data.status === 'fail') {
      // Handle specific error codes
      switch (data.errors.code) {
        case 400:
          if (data.errors.details) {
            // Validation errors with field details
            console.error('Validation errors:', data.errors.details);
            Object.entries(data.errors.details).forEach(([field, error]) => {
              console.error(`${field}: ${error}`);
            });
          } else {
            // General bad request
            console.error('Error:', data.errors.message);
          }
          break;
        case 404:
          console.error('Not found:', data.errors.message);
          break;
        case 500:
          console.error('Server error:', data.errors.message);
          break;
        default:
          console.error('Unexpected error:', data.errors.message);
      }
      return null;
    }
    
    // Success
    return data.data.user;
  } catch (error) {
    // Network or parsing errors
    console.error('Request failed:', error);
    return null;
  }
}

// Usage
const user = await loginUser('user@example.com', 'password123');
if (user) {
  console.log('Logged in as:', user.fullname);
}

Best Practices

Always Check Status

Always verify the status field before processing response data.

if (data.status === 'fail') {
  // Handle error
} else {
  // Process data
}

Display Field-Specific Errors

Show validation errors next to their respective form fields.

if (data.errors.details) {
  Object.entries(data.errors.details)
    .forEach(([field, error]) => {
      showFieldError(field, error);
    });
}

Implement Retry Logic

Retry failed requests for server errors (500+) with exponential backoff.

if (error.code >= 500) {
  await retryWithBackoff(request);
}

Log Errors

Log errors for debugging, especially server errors.

console.error('API Error:', {
  code: error.code,
  message: error.message,
  endpoint: '/api/login'
});

Common Error Scenarios

User Registration

Possible Errors:

Email validation error (invalid format)
Email already exists
Password too short
Password mismatch

See validation rules in src/auth/schema.ts:13-28

User Login

Possible Errors:

Invalid credentials
Missing email or password
Server connection error

See error handling in src/auth/service.ts:153-174

Token Refresh

Possible Errors:

Refresh token missing
Refresh token expired
Invalid refresh token
Token not in database

See validation in src/auth/service.ts:177-231

Product Operations

Possible Errors:

Product not found (404)
Validation errors (missing name/price)
Image upload errors (wrong format, too many images)
Server errors during file upload

Next Steps

Authentication

Learn about authentication and token management

Rate Limits

Understand API usage limits

API Reference

Explore all available endpoints

Products API

Work with products

Get Started

Guides

Database

Overview

Error Response Format

Response Fields

HTTP Status Codes

Error Types

Validation Errors

Authentication Errors

Not Found Errors

Bad Request Errors

Server Errors

Custom Validation Errors

Error Handling Examples

Best Practices

Always Check Status

Display Field-Specific Errors

Implement Retry Logic

Log Errors

Common Error Scenarios

Next Steps

Authentication

Rate Limits

API Reference

Products API

Build docs developers (and LLMs) love

Get Started

Guides

Database

Documentation Index

​Overview

​Error Response Format

​Response Fields

​HTTP Status Codes

​Error Types

​Validation Errors

​Authentication Errors

​Not Found Errors

​Bad Request Errors

​Server Errors

​Custom Validation Errors

​Error Handling Examples

​Best Practices

Always Check Status

Display Field-Specific Errors

Implement Retry Logic

Log Errors

​Common Error Scenarios

​Next Steps

Authentication

Rate Limits

API Reference

Products API

Build docs developers (and LLMs) love

Overview

Error Response Format

Response Fields

HTTP Status Codes

Error Types

Validation Errors

Authentication Errors

Not Found Errors

Bad Request Errors

Server Errors

Custom Validation Errors

Error Handling Examples

Best Practices

Common Error Scenarios

Next Steps