Errors

When a request fails, the API returns problem details, a standard JSON error format (RFC 9457), with the content type application/problem+json. Every error has a stable code. Let your code check code, never the title or detail, which are written for people to read.

{
  "type": "https://algotradertools.com/docs/errors#validation_failed",
  "title": "Validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "lot_value: Use a number above 0 and up to 1000.",
  "errors": [
    { "path": "/lot_value", "code": "invalid", "message": "Use a number above 0 and up to 1000." }
  ],
  "request_id": "b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
  "doc_url": "https://algotradertools.com/docs/errors#validation_failed"
}

Handling errors

Retry these:

• 429 after the number of seconds in Retry-After
• 500, 502, 503 and 504, with exponential backoff

Don't retry other errors without changing the request first. A 400, 401, 403, 404, 405, 406, 409 or 415 will fail the same way again.

Retrying a POST is safe for accounts and followers. If the first attempt went through, the second fails with already_connected or already_following instead of creating a duplicate. A retried POST /v1/copiers can create a second copier. If you didn't get a response to one, list your copiers before you retry it.

const API = "https://api.algotradertools.com/v1";
const MAX_ATTEMPTS = 5;

async function request(method: string, path: string, body?: unknown) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`${API}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.ATT_API_KEY}`,
        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
      },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
    if (response.status === 204) return null;
    const payload = await response.json();
    if (response.ok) return payload;

    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt === MAX_ATTEMPTS) {
      throw new Error(`${payload.code}: ${payload.detail} (request ${payload.request_id})`);
    }
    const retryAfter = Number(response.headers.get("Retry-After"));
    const wait = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait));
  }
}

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

405 Method Not Allowed

406 Not Acceptable

409 Conflict

415 Unsupported Media Type

429 Too Many Requests

500 and above

Field-level codes

A validation_failed error lists each problem in errors, with a path to the field and a code. Besides the generic codes required, invalid, null, blank, max_length, invalid_choice, does_not_exist, incorrect_type, min_value, max_digits and max_decimal_places, these say exactly what is wrong:

A close_positions query parameter that isn't true, false, 1 or 0 fails with validation_failed too, with the path /close_positions.