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 and error.code before retrying.
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

Check the HTTP status and machine-readable error code before deciding whether to retry, prompt for corrected input, or pause validation.

{
  "success": false,
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Validation usage limit exceeded."
  }
}

Code	HTTP	Meaning
VALIDATION_ERROR	422	Request payload failed validation.
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.
TEAM_NOT_FOUND	401	Authenticated team context was not found.
NO_SUBSCRIPTION	402	Team does not have an active Soryxa subscription.
SUBSCRIPTION_INACTIVE	402	Subscription exists but is not active.
USAGE_LIMIT_EXCEEDED	429	Plan validation allowance has been reached.
USAGE_CHECK_ERROR	500	Usage check failed before validation could complete.

Do not retry input errors

Fix the payload before retrying a VALIDATION_ERROR 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.