Error Codes Reference

Reference every error code the Sovera Integration Layer API returns.

Errors are predictable. Every failure—whether a missing field, a revoked key, or an upstream outage—comes back in one envelope with the same shape. Branch your logic on the HTTP status for the broad category and on the code for the exact reason; treat the human-readable message as a hint to log or surface, not something to parse. Each code is derived from the error: the API first matches keywords in the message (for example, a "not found" about a user yields USER_NOT_FOUND), then falls back to a code based on the HTTP status.

Error Response Format

Every error returns success: false, an errors array, and a meta block. The errors array carries one or more objects, each with a stable code and a message. The meta block carries the timestamp, the API version, and a trace_id that ties the response to server-side logs—capture it for every failed request.

{
  "success": false,
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human-readable error description"
    }
  ],
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

HTTP Status Codes

Authentication & Authorization Errors

The code for authentication failures is always UNAUTHORIZED (401) or FORBIDDEN (403); the specific reason is in the message. A 401 means the credential is missing, malformed, revoked, or expired—fix the header or mint a fresh user token. A 403 means the credential is valid but lacks reach—switch to the API key (or master key) the endpoint expects.

How to fix:

# Owner API Key (most User API endpoints)
curl -H "x-api-key: YOUR_OWNER_API_KEY" ...

# Re-generate a user token
curl -X POST "BASE_URL/users/{user_id}/token" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Validation Errors

Field validation fails with 422 Unprocessable Entity. The errors array carries one entry per invalid field, so you can map each failure back to its input.

Example:

{
  "success": false,
  "errors": [
    {
      "code": "UNPROCESSABLE_ENTITY",
      "message": "email must be a valid email address"
    },
    {
      "code": "UNPROCESSABLE_ENTITY",
      "message": "phone_number must be a valid mobile number for the country"
    }
  ],
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

User Errors

Wallet Errors

Trading / Order Errors

Withdrawal Errors

System & Gateway Errors

Debugging Tips

Trace IDs

Every response carries a trace_id in meta that correlates it with server-side logs. Log it for every failed request and include it whenever you report an issue—it's the fastest way for support to find the exact call.

{
  "meta": {
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

Or pass your own x-trace-id to stitch a request to your application logs end-to-end. The API echoes it back instead of generating one:

curl -H "x-trace-id: my-custom-trace-123" \
  -H "x-api-key: YOUR_API_KEY" \
  BASE_URL/users

Common Troubleshooting

1. 401 Unauthorized — Check x-api-key header is present and lowercase, key is not revoked
2. 403 Forbidden — Endpoint requires Owner API Key or higher permission level
3. 404 Not Found — Verify the resource ID and that it belongs to your client account
4. 409 Conflict — A resource with that email, phone, or name already exists
5. 400 Bad Request — Read the message field — it will point to the specific field or rule that failed
6. 429 Too Many Requests — Implement exponential backoff:

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

7. 502 / 504 — External service (Utila or SFOX) issue. Retry after a short delay.

Error Handling Example

import axios from 'axios';

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

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

      switch (code) {
        case 'UNAUTHORIZED':
          // Re-authenticate
          break;
        case 'RATE_LIMIT_EXCEEDED':
          // Back off and retry
          break;
        case 'QUOTE_EXPIRED':
          // Fetch 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]