# API Errors

Every non-2xx response from the Simmit API returns the same JSON envelope. Branch on `code`, log `error`, and read `meta` when you need additional context.

## Response shape

```json
{
  "error": "Human-readable message describing what went wrong.",
  "code": "machine_readable_code",
  "meta": {},
  "requestId": "req_4f9a2c1e8b7d4f0a9c3e5d6b7a8f1e2d"
}
```

**`error`** _(string)_

Human-readable message safe to log. Don't branch on it; the wording can change.

**`code`** _(string)_

Stable, machine-readable identifier for this error. Branch on this.

**`meta`** _(object | null)_

Additional structured context relevant to this specific `code`. Shape varies by `code`; `null` when no additional context applies.

**`requestId`** _(string)_

Correlation id for this request, identical to the `X-Request-Id` response header.

## Request IDs

Every response carries an `X-Request-Id` header: a unique id for that request, like `req_4f9a2c1e8b7d4f0a9c3e5d6b7a8f1e2d`. Error responses also echo it in the body as `requestId`.

Log it and include it in any support ticket. It points us at the exact request.

```ts
const res = await fetch('https://api.simmit.com/v1/simc/credits', {
  headers: { Authorization: `Bearer ${apiKey}` }
})
const requestId = res.headers.get('X-Request-Id')
if (!res.ok) {
  console.error(`Simmit request ${requestId} failed with ${res.status}`)
}
```

## Status codes

**400**

Validation failed. The body, query, header, or path didn't match the endpoint's schema.

**401**

Missing, invalid, expired, or revoked `Authorization` header. Re-issue your secret key under [Clients & Keys](/clients).

**402**

Your account doesn't have enough credits to reserve this job, or it's inactive. Top up or reactivate, then retry.

**409**

Idempotency conflict (reused key with a different payload), or `/result` was polled before the job reached a terminal status.

**413**

Request body exceeds the platform limit. Most commonly profile text above 2 MB, or too many profileset variants in one input.

**422**

Input was syntactically valid but semantically rejected. Most commonly a SimC profile containing a blocked directive (see [Input Constraints](/docs/api/input-constraints)), or a terminal job that produced no result payload.

**429**

Rate limit exceeded, or your account's in-flight job limit is full. Honour `Retry-After`. Responses include `X-RateLimit-Remaining` and `X-RateLimit-Reset` where applicable.

**500**

Unhandled error on Simmit's side. Safe to retry with exponential backoff.

**503**

Simmit is in a maintenance window or a transient dependency is degraded. Retry after the window or with exponential backoff.

## Useful error codes

You don't need to memorize every `code` value. The codes below are the ones a real integration is most likely to branch on. The [API Reference](/docs/api-reference) documents the full set per endpoint.

**`insufficient_credits`**

402. Your account ran out of credits for this job's reservation. Top up before retrying.

**`inactive_entitlement`**

402. Your account is inactive. Activate before retrying.

**`idempotency_key_reuse`**

409. The `idempotency-key` header was reused with a different request body. See [Idempotency](/docs/api-advanced/idempotency).

**`result_not_ready`**

409. `/result` was polled before the job reached a terminal status. Use `/status` first.

**`result_unavailable`**

422. The job is terminal but no result payload was produced (for example, an early failure). Inspect `meta.status` and the job's `errorCode`.

**`input_sanitized_rejected`**

422. The submitted SimC profile contained a directive Simmit doesn't allow. `meta.docsUrl` links to the constraints. See [Input Constraints](/docs/api/input-constraints).

**`rate_limit_exceeded`**

429. Too many requests for this client in the current window. Honour `Retry-After`.

**`max_active_jobs_exceeded`**

429. Your account already has the maximum number of jobs in flight. Wait for some to finish.

**`api_maintenance`**

503. Simmit is in a planned maintenance window. Retry once the window closes.

---

_HTML version: https://docs.staging.simmit.gg/docs/api/errors · Full docs index: https://docs.staging.simmit.gg/llms.txt_