Error Codes Reference

Errors are predictable. Every failure—a missing field, a revoked key, an upstream outage—comes back in one envelope with the same shape. Branch on the HTTP status for the category and on code for the exact reason; treat message as a hint to log or show, never something to parse.

Error Response Format

Every error returns success: false, an errors array, and meta. Each error carries a stable code, a message, and, when it points at your input, a source with a pointer (body field), parameter (path or query parameter), or header. See API conventions for the full rules.

{
  "success": false,
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "address should not be empty",
      "source": { "pointer": "/address" }
    },
    {
      "code": "VALIDATION_ERROR",
      "message": "amount must be a positive decimal string, e.g. \"0.01000000\"",
      "source": { "pointer": "/amount" }
    }
  ],
  "meta": {
    "timestamp": "2026-10-12T14:03:11Z",
    "version": "v1",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

HTTP Status Codes

Generic Codes

Any endpoint can return these. When an error has no more specific code, the code follows the HTTP status.

Idempotency Errors

See Idempotency.

Authentication Errors

A 401 means fix the header or get a fresh token. A 403 means the credential is valid but lacks reach—use the credential the endpoint expects. See Authentication.

User Errors

Wallet and Address Errors

Transfer Errors

Withdrawal Errors

Trading Errors

A quote the venue rejects at execution doesn't fail the call: the order comes back 201 with status: "FAILED" and status_reason.code: "QUOTE_REJECTED". If the venue's answer is lost, the order comes back 201 with status: "PENDING" and status_reason.code: "EXECUTION_OUTCOME_UNKNOWN": the quote may have executed, so don't retry it; follow the order until it settles.

Customer Errors

Debugging Tips

Trace IDs

Every response carries a trace_id in meta and in the x-trace-id response header. Log it for every failed request and include it when you report an issue—it's the fastest way for support to find the exact call.

Pass your own x-trace-id (32 lowercase hex characters) to stitch a request to your application logs. The API keeps it and echoes it back; a hyphenated UUID is compacted, and any other value is replaced with a fresh id instead of failing the request.

curl -H "x-trace-id: 4bf92f3577b34da6a3ce929d0e0e4736" \
  -H "x-api-key: YOUR_API_KEY" \
  "https://api.sandbox.sovera.io/sovx/v1/users"

Common Troubleshooting

1. 401 Unauthorized—Check the x-api-key or Authorization: Bearer header, and mint a fresh user token if it's older than 24 hours.
2. 403 Forbidden—Use the credential the endpoint expects.
3. 404 Not Found—Verify the id and that it belongs to your customer (and, with a user token, to that user).
4. 409 Conflict—A resource with that email, phone, or id already exists, or the same idempotency key is still running.
5. 422 Unprocessable Entity—Read source to find the field, parameter, or header that failed, or check the resource's status for INVALID_STATE_TRANSITION.
6. 429 Too Many Requests—Wait the retry-after seconds, then back off exponentially:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = Number(error.response.headers['retry-after'] ?? 2 ** i);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

7. 502 / 504—An upstream service had an issue. Retry after a short delay with the same x-idempotency-key.

Error Handling Example

import axios from 'axios';

async function handleApiCall() {
  try {
    const response = await axios.get('https://api.sandbox.sovera.io/sovx/v1/users', {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    });
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const apiError = error.response?.data;
      const { code, message, source } = apiError?.errors?.[0] ?? {};
      const traceId = apiError?.meta?.trace_id;

      console.error(`API Error [${code}]: ${message} ${JSON.stringify(source ?? {})} (trace: ${traceId})`);

      switch (code) {
        case 'UNAUTHORIZED':
          // Re-authenticate or mint a fresh user token
          break;
        case 'RATE_LIMIT_EXCEEDED':
          // Wait retry-after seconds and retry
          break;
        case 'QUOTE_EXPIRED':
          // Request a new quote and retry
          break;
        default:
          throw error;
      }
    }
    throw error;
  }
}

Support

Hit persistent errors? Contact support with:

• Trace ID from the error response
• Timestamp of the request
• Endpoint and HTTP method called
• Request body / parameters (redact sensitive values)
• Email: [email protected]