Each validation request is designed to return usage fields so your application can track remaining allowance and react before a validation limit affects signup or CRM workflows.
Capacity signals
Number of validations remaining after the current request.
Plan allowance used to calculate remaining validations.
Current-period usage returned by the usage endpoint.
Whether the token team has a subscription record available for usage reporting.
Whether the subscription is active for the current usage period.
Error code returned when the current plan allowance is exhausted.
When validation allowance is exhausted, handle the usage-limit error separately from email quality.
{
"success": false,
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Validation usage limit exceeded."
}
}Use GET /api/v1/usage with a token that has the usage scope to read current plan usage. The endpoint reports usage and remaining allowance without consuming a validation credit.
GET /api/v1/usage
Authorization: Bearer $SORYXA_API_KEY
Accept: application/jsonThe response includes subscription state, plan name, limit, used count, remaining allowance, and current-period dates.
{
"success": true,
"data": {
"has_subscription": true,
"subscription_active": true,
"subscription_type": "paid",
"plan_name": "Growth",
"limit": 10000,
"used": 2412,
"remaining": 7588,
"period_started_at": "2026-06-01",
"period_ends_at": "2026-07-01"
}
}Usage planning works best when each validation is tied to a specific workflow and measurable outcome.
Estimate one validation for each signup attempt that reaches your backend validation step.
Validate new or changed addresses before syncing them into CRM or lifecycle workflows.
Run targeted checks before send-heavy workflows when address quality is uncertain.
Usage planning protects the workflow around validation. The address may be valid, invalid, or risky, but a usage-limit error only means the account needs capacity handling.
Keep usage dashboards separate from email quality dashboards. Product teams need to know why an address was allowed, blocked, or reviewed, while account owners need to know whether the current plan can support the next signup, import, or pre-send review run.
For live signup paths, review the threshold where the team should upgrade, queue validations, or temporarily change the workflow. Waiting until the first limit error appears usually creates a worse user experience than monitoring remaining allowance ahead of time.
Separate signup checks, CRM intake checks, and pre-send review checks before choosing a plan. Each workflow has a different volume pattern and different urgency when allowance runs low.
Use remaining and limit fields to alert before validation stops. This is especially important for signup flows where a limit error can affect user onboarding.
Decide whether over-limit requests should pause, queue, or show a controlled review state. Avoid mixing usage exhaustion with email quality decisions.