Error Codes

List of JunkMail API error codes

Error Format

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description de l'erreur",
    "details": {}
  }
}

HTTP Codes

Code	Meaning
200	Success
201	Resource created
400	Invalid request
401	Not authenticated
403	Access forbidden
404	Resource not found
429	Too many requests
500	Server error

---

Authentication Errors

INVALID_API_KEY

{
  "code": "INVALID_API_KEY",
  "message": "La clé API est invalide ou expirée"
}

Solution: Verify that your API key is correct and active.

MISSING_API_KEY

{
  "code": "MISSING_API_KEY",
  "message": "Aucune clé API fournie"
}

Solution: Add the Authorization: Bearer jm_live_xxxx header.

INSUFFICIENT_SCOPE

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Cette action nécessite le scope 'emails:write'",
  "details": {
    "requiredScopes": ["emails:write"],
    "providedScopes": ["emails:read"]
  }
}

Solution: Create a new API key with the required scopes.

---

Validation Errors

VALIDATION_ERROR

{
  "code": "VALIDATION_ERROR",
  "message": "Erreur de validation",
  "details": {
    "fields": {
      "alias": "L'alias doit contenir entre 3 et 30 caractères"
    }
  }
}

ALIAS_TAKEN

{
  "code": "ALIAS_TAKEN",
  "message": "Cet alias est déjà utilisé"
}

INVALID_DOMAIN

{
  "code": "INVALID_DOMAIN",
  "message": "Ce domaine n'est pas configuré pour votre compte"
}

---

Resource Errors

RESOURCE_NOT_FOUND

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Adresse non trouvée",
  "details": {
    "resourceType": "address",
    "resourceId": "addr_invalid"
  }
}

ADDRESS_EXPIRED

{
  "code": "ADDRESS_EXPIRED",
  "message": "Cette adresse a expiré"
}

---

Rate Limit Errors

RATE_LIMIT_EXCEEDED

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de requêtes atteinte",
  "details": {
    "limit": 100,
    "resetAt": "2024-01-16T14:35:00Z"
  }
}

Solution: Wait for the reset or reduce the frequency of your requests.

QUOTA_EXCEEDED

{
  "code": "QUOTA_EXCEEDED",
  "message": "Limite d'adresses atteinte pour votre plan",
  "details": {
    "limit": 10,
    "current": 10
  }
}

Solution: Delete existing addresses or upgrade to a higher plan.

---

Server Errors

INTERNAL_ERROR

{
  "code": "INTERNAL_ERROR",
  "message": "Une erreur interne s'est produite"
}

Solution: Retry the request. If the problem persists, contact support.

SERVICE_UNAVAILABLE

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Le service est temporairement indisponible"
}

Solution: Retry in a few minutes.