# 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": {}
}
```

**`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.

## 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://simmit.com/docs/api/errors · Full docs index: https://simmit.com/llms.txt_