Error reference

Soryxa API Errors

Handle Soryxa errors explicitly so signup and CRM workflows can distinguish bad input, missing authentication, inactive billing, usage limits, and temporary service failures.

Handling order

1 Check HTTP status first. Validate-email request errors expose top-level error_code; batch creation 422 responses expose errors instead.
2 Route auth, subscription, and usage errors to account handling.
3 Keep API failures separate from allow, block, and review email decisions.

Documentation map

Pick the product or implementation step before you wire authentication, responses, limits, or events.

Suite docs

Docs home Company Domain Lookup Elvesora Enrichment

Soryxa API

Overview Validate email Reason codes API errors Usage and credits Batch validation Rules and review queue Webhooks and connectors

Error response shape

Validate-email request validation and documented authentication, subscription, usage, and batch-state errors expose a machine-readable error_code. Batch creation input validation is the exception: its HTTP 422 body returns success, message, and errors without error_code.

{
  "success": false,
  "message": "You have reached your usage limit for this billing period. Please upgrade your plan.",
  "error_code": "USAGE_LIMIT_EXCEEDED",
  "data": {
    "limit": 250,
    "used": 250,
    "remaining": 0,
    "period_ends_at": "2026-08-01"
  }
}

Code	HTTP	Meaning
VALIDATION_ERROR	422	The validate-email request payload failed validation. Batch creation 422 responses use an errors object without error_code.
INVALID_AUTH_HEADER	401	Authorization header is malformed.
MISSING_TOKEN	401	Bearer token was not provided.
INVALID_TOKEN	401	Bearer token could not authenticate the request.
TOKEN_EXPIRED	401	Bearer token has passed its expiration time.
TEAM_NOT_FOUND	401	Authenticated team context was not found.
TOKEN_NOT_FOUND	401	Scope middleware could not find the authenticated token on the request.
INSUFFICIENT_SCOPE	403	Token does not include a scope required by the endpoint.
NO_SUBSCRIPTION	402	Team does not have an active Soryxa subscription.
SUBSCRIPTION_INACTIVE	402	Subscription exists but is not active.
TOKEN_RATE_LIMIT_EXCEEDED	429	Token reached its configured per-minute request limit.
USAGE_LIMIT_EXCEEDED	429	Plan validation allowance has been reached.
INSUFFICIENT_CREDITS	429	A batch contains more rows than the team has remaining credits.
NOT_FOUND	404	The requested team-scoped batch job was not found.
JOB_NOT_TERMINAL	409	A batch export was requested before the job reached a terminal state.
INVALID_TRANSITION	409	The batch cannot move to the requested state, such as cancelling a completed job.
USAGE_CHECK_ERROR	500	Usage check failed before validation could complete.

Do not retry input errors

Fix the payload before retrying a validate-email VALIDATION_ERROR response or a batch creation HTTP 422 response.

Pause on account errors

Treat authentication and subscription errors as configuration issues rather than address quality decisions.

Plan limit handling

Route USAGE_LIMIT_EXCEEDED to plan review, queueing, or a user-visible fallback.

Error handling guidance

Error codes describe the request or account state, not the quality of the submitted address. Keep them separate from allow, block, and review decisions in logs and analytics.

This separation matters during incidents and billing changes. A spike in invalid addresses should trigger product or abuse review, while authentication, subscription, and usage errors should route to the account owner responsible for API configuration and plan capacity.

Log the error code, HTTP status, request context, and retry decision together. That gives your troubleshooting workflow enough context without confusing service issues with validation outcomes.

Authentication errors are configuration issues

A missing or invalid token should pause validation and prompt the API owner to fix credentials. It should not mark an email address as risky.

Subscription errors need account handling

Payment-required responses mean the team account cannot validate at the moment. Route these to plan review, billing recovery, or a queueing strategy.

Usage limits are capacity signals

When usage is exhausted, decide whether to stop new validations, queue them, or move to a plan with more allowance before user-facing workflows are affected.

Temporary service errors need fallback logic

A service or usage-check failure should produce a controlled fallback path. For signup flows, review is usually safer than silently allowing or blocking the address.