Skip to main content

Error Codes

Every eCore API endpoint uses standard HTTP status codes. This table lists the codes you can expect across the API.

Status Codes​

CodeNameMeaning
200OKRequest succeeded
201CreatedA new resource was created (e.g., an email validation job)
204No ContentRequest succeeded but the response has no body (e.g., delete)
400Bad RequestMissing, malformed, or invalid parameters
401UnauthorizedInvalid, expired, or missing token
402Payment RequiredInsufficient credits in the wallet for the operation
404Not FoundThe requested resource (record, job) does not exist or belongs to another user
429Too Many RequestsDaily test-token usage cap exceeded
500Internal Server ErrorUnexpected server-side failure — retry or contact support

Response Body Patterns​

200 OK with a logical "not found" result​

Some endpoints (notably enrichment) return 200 OK with a status: "not_found" field rather than 404, so the caller can distinguish the data isn't in our database from your request was malformed. No credit is charged in this case.

{
  "success": true,
  "status": "not_found",
  "message": "Email not found",
  "remaining_credits": 100
}

400 Bad Request​

Returned for any validation failure on the request body, query parameters, or uploaded files. The body typically contains a field-level error map:

{ "error": "Provide either a 'csv_file' upload or an 'emails' list." }
{ "emails": { "3": ["Not a valid email address."] } }

401 Unauthorized​

{ "detail": "Invalid token." }

Causes:

  • Missing Authorization header.
  • Token is expired or revoked.
  • Token format is wrong (e.g., missing Token prefix).

402 Payment Required​

{
  "error": "Insufficient credits. You need 50 credits but have 12.",
  "required": 50,
  "balance": 12
}

The pre-charge wallet check rejected the request before doing any work. No credits are deducted.

404 Not Found​

{ "detail": "Not found." }

Either the resource truly doesn't exist, or it belongs to another user. The API does not differentiate between "doesn't exist" and "exists but not yours" — both return 404 to avoid leaking the existence of other users' resources.

429 Too Many Requests​

{
  "error": {
    "message": "Daily test-token limit exceeded.",
    "current_usage": 100,
    "daily_limit": 100,
    "resets_at": "midnight UTC"
  }
}

Applies only to test tokens. Live API tokens have no per-day limit but are still bound by wallet balance and per-endpoint plan limits.

Endpoint-specific Errors​

Each endpoint page lists the errors it can return. See: