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

#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.

#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.