Skip to main content

Error reference

All errors return a JSON body:

{ "message": "<reason>" }

Validation failures add an errors array with the exact field(s) that failed. Some endpoints add structured fields — documented per endpoint.

Status codes​

400 — Bad request​

Validation error or a business rule violation that doesn't need a more specific code (e.g. "insufficient SOL balance", "bots in this state can't be canceled").

{
  "message": "Validation failed",
  "errors": [
    { "msg": "nHoldersCount must be one of: 500, 1000, 2500, 5000, 10000, 20000", "path": "nHoldersCount" }
  ]
}

401 — Unauthorized​

Missing / expired / revoked access token; missing x-api-key on an auth endpoint; reused refresh token. Get a fresh pair via /auth/api/refresh or /auth/api/token and retry.

403 — Forbidden​

API key invalid or deactivated.

404 — Not found​

Resource doesn't exist or doesn't belong to the caller. Endpoints that take a list of ids include a missing array pointing at the bad entries.

409 — Conflict​

State that should be singleton already exists:

  • /referrals/create when the user already has a code
  • /holders/initialize when the user already has a pending order

Response body includes the existing id so you can recover.

500 — Internal server error​

Generic server-side failure. No implementation details leak into the response. Retry with exponential backoff.

Per-wallet / per-entry failures​

Some endpoints return 200 even when part of the work failed, and report per-entry outcome.

POST /trading/swap returns an aResults array:

{
  "success": true,
  "aResults": [
    { "sWalletAddress": "…", "signature": "3k…", "success": true },
    { "sWalletAddress": "…", "signature": null, "success": false,
      "reason": "insufficient SOL", "required": 5050000, "current": 0 }
  ],
  "stats": { "requested": 2, "eligible": 1, "succeeded": 1, "failed": 1 }
}

POST /token/create pre-validates balances and rejects the whole call with 400 if any wallet is short:

{
  "message": "insufficient SOL balance on one or more wallets",
  "wallets": [
    { "type": "sniper#2", "address": "…", "requiredSol": 0.11, "currentSol": 0.05 }
  ]
}

Retry policy​

  • 5xx — exponential backoff, max ~3 retries.
  • 401 with "expired" — refresh the token, retry once.
  • 400 / 404 / 409 — don't retry; same input gets the same result.
  • Fire-and-forget timeouts (/token/create, /holders/initialize) — don't retry the HTTP call; the job may already be running. Use the status endpoint to reconcile.