Error Codes

All API errors follow a consistent format with actionable error codes.

Error Response Format

Response401

{
  "statusCode": 401,
  "error": "UNAUTHORIZED",
  "message": "Invalid API key",
  "requestId": "req_abc123",
  "timestamp": "2024-01-10T12:00:00Z"
}

Authentication Errors (401)

MISSING_API_KEY

Cause: Authorization header not provided

Solution:

fetch('https://api.mumin.ink/v1/hadiths/1', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY' // ← Add this
  }
})

INVALID_API_KEY

Cause: API key is invalid or has been revoked

Solution: Generate a new API key in your dashboard (opens in a new tab)

EXPIRED_API_KEY

Cause: API key has expired

Solution: Create a new API key

Rate Limit Errors (429)

RATE_LIMIT_EXCEEDED

Cause: Too many requests in a short period

Solution:

Wait for the rate limit to reset (see X-RateLimit-Reset header)
Implement exponential backoff
Upgrade your plan for higher limits

// Check rate limit headers
const response = await fetch('...')
const remaining = response.headers.get('X-RateLimit-Remaining')
const reset = response.headers.get('X-RateLimit-Reset')
 
if (remaining === '0') {
  console.log(`Rate limit resets at: ${new Date(reset * 1000)}`)
}

Payment Errors (402)

BALANCE_DEPLETED

Cause: API key balance is zero

Solution: Top up credits (opens in a new tab)

Validation Errors (400)

INVALID_HADITH_ID

Cause: Hadith ID out of range (1-7563)

Response400

{
  "statusCode": 400,
  "error": "INVALID_HADITH_ID",
  "message": "Hadith ID must be between 1 and 7563",
  "received": 99999
}

INVALID_LANGUAGE_CODE

Cause: Unsupported language code

Supported: ar, en, ru, uz

Resource Errors (404)

NOT_FOUND

Cause: Requested resource doesn't exist

Response404

{
  "statusCode": 404,
  "error": "NOT_FOUND",
  "message": "Hadith with ID 99999 not found"
}

Server Errors (500)

INTERNAL_SERVER_ERROR

Cause: Unexpected server error

What to do:

Retry the request
Check status page (opens in a new tab)
Contact support with requestId

Retry Logic Example

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options)
 
      if (response.ok) {
        return await response.json()
      }
 
      // Rate limit - wait and retry
      if (response.status === 429) {
        const resetTime = response.headers.get('X-RateLimit-Reset')
        const waitMs = resetTime * 1000 - Date.now()
        await new Promise(resolve => setTimeout(resolve, waitMs))
        continue
      }
 
      // Server error - exponential backoff
      if (response.status >= 500) {
        const delay = Math.pow(2, i) * 1000 // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }
 
      // Client error - don't retry
      throw new Error(`HTTP ${response.status}`)
    } catch (error) {
      if (i === maxRetries - 1) throw error
    }
  }
}

HTTP Status Code Summary

Code	Name	Description
200	OK	Request successful
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid API key
402	Payment Required	Insufficient balance
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Books Rate Limits