API errors

View as Markdown

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"
}

#errorstring

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

#codestring

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

#metaobject | null

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

#requestIdstring

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.

TypeScript

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.

#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), 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 documents the full set per endpoint.

#insufficient_credits

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

#inactive_entitlement

Your account is inactive. Activate before retrying.

#idempotency_key_reuse

The idempotency-key header was reused with a different request body. See Idempotency.

#result_not_ready

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

#result_unavailable

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

The submitted SimC profile contained a directive Simmit doesn't allow. meta.docsUrl links to the constraints. See Input Constraints.

#rate_limit_exceeded

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

#max_active_jobs_exceeded

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

#api_maintenance

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