Solverify API Error Codes

Use this reference to understand Solverify API error codes, request validation limits, billing failures, task capacity errors, and recommended recovery actions. These errors can be returned by createTask, getTaskResult, getBalance, profile, and activeTasks requests.

Solverify customer API clients must inspect both the HTTP response and the JSON errorId. A successful HTTP request can still contain an API-level validation, authentication, billing, or task error.

Standard Solverify API Error Response

Most customer-facing validation and business errors use a consistent JSON structure and may be returned with HTTP 200:

{
  "errorId": 1,
  "errorCode": "ERROR_CODE_HERE",
  "errorDescription": "Human-readable explanation"
}

Some internal and node routes use HTTP status codes such as 400, 401, 404, 409, or 500. Always handle transport failures and non-success HTTP statuses in addition to checking errorId.

Request and Validation Errors

These errors indicate that the request or task payload must be corrected before retrying.

Do not repeatedly retry validation errors with the same payload. Correct the request first.

API Key and Account Errors

Store API keys in environment variables or a secret manager. Never log the full clientKey when recording an error.

Billing and Task Limit Errors

Use the Get Balance API to check available credit, the Get Profile API for account-wide task counters, and the Active Tasks API for website-level queue information.

Capacity and Task Processing Errors

Internal API Errors

Do not retry indefinitely. Set a maximum attempt count or overall deadline and log enough non-sensitive context to investigate repeated failures.

API Error Handling Examples

These examples demonstrate the important two-stage check: validate the HTTP response first, then inspect errorId in the JSON body.

curl --request POST \
  --url https://solver.solverify.net/getBalance \
  --header "Content-Type: application/json" \
  --data '{"clientKey":"YOUR_API_KEY"}'

Request Validation Limits

Requests and task fields must stay within these limits:

Validate payloads before sending them. Client-side validation reduces failed requests and helps prevent temporary request restrictions caused by repeated invalid submissions.

Active Task Limits

Pay-per-solve accounts default to a maximum of 20 active tasks unless configured otherwise. Thread and subscription accounts are limited by their assigned thread count while billing is active.

Both pending and processing tasks count as active work. If a limit is reached, wait for existing tasks to complete before creating more tasks.

Retry Guidance

Use error-specific retry behavior instead of retrying every failure:

Frequently Asked Questions

Why can a Solverify API error return HTTP 200?

Customer API errors use a consistent JSON response shape. HTTP 200 confirms that the API handled the request, while errorId: 1 reports a validation, authentication, billing, capacity, or task-level failure.

Should I only check the HTTP status code?

No. Check the HTTP status and parse the JSON response. A response can have a successful HTTP status while containing errorId: 1.

Which error means the Solverify API key is invalid?

ERROR_INVALID_KEY means the supplied clientKey was not found or is invalid. Verify that the correct key was loaded and that it does not contain extra spaces.

What should I do after ERROR_INSUFFICIENT_BALANCE?

Stop creating tasks and add funds to the account. Use POST /getBalance to confirm the updated balance before resuming submissions.

Should I retry ERROR_NO_CAPACITY immediately?

No. Wait before retrying and use bounded backoff. Rapid retries add request volume without creating solver capacity.

How should I handle ERROR_TASK_FAILED?

Stop polling that task ID and inspect errorDescription. Correct any task-specific issue before deciding whether to create a replacement task.

What information should I log for API errors?

Log the endpoint, errorCode, errorDescription, task ID when available, attempt count, and timestamp. Do not log the full API key, proxy credentials, or sensitive task payloads.