API errors

Every failure uses the same envelope. This page lists the codes you can actually receive and what your integration should do about each one.

Shape

What a failure looks like

details carries a machine-readable code where one applies.

{
  "success": false,
  "data": null,
  "message": "Order number is required.",
  "details": { "code": "SIMCOAI_ORDER_NUMBER_REQUIRED" },
  "requestId": "req_h9afi6vi"
}

Codes

Status codes and how to handle them

Branch on details.code where present, and on the HTTP status otherwise.

Status	Code	Cause	What to do
400	—	Malformed JSON or an unsupported table name	Fix the request. Retrying will not help.
401	—	Missing or invalid API key	Check the key and header name. Rotate if the key may have leaked.
403	—	Key is valid but lacks the required scope	Issue a key with the scope the endpoint needs.
404	`SIMCOAI_RESOURCE_NOT_FOUND`	No record with that id on your account	Do not retry. Confirm the id and that it belongs to you.
409	`WORKFLOW_DUPLICATE`	A matching workflow already exists	Treat as success. See idempotency.
422	`SIMCOAI_ORDER_NUMBER_REQUIRED`	Creating an order without `order_number`	Add the field and resend.
422	`SIMCOAI_ESCALATION_REASON_REQUIRED`	Creating an escalation without `reason`	Add the field and resend.
429	—	Rate limit exceeded	Back off and retry later. See rate limits.
5xx	—	Something failed on our side	Retry with backoff. If it persists, quote the `requestId`.

Practice

Handling errors well

Retry only 429 and 5xx. A 4xx other than 429 will fail identically on retry.
Use exponential backoff with jitter. Immediate retries make a rate limit worse.
Log the requestId on every failure. It is the fastest route to an answer from support.
Never surface raw API errors to your customers. Map them to your own wording.

Careful. A 409 WORKFLOW_DUPLICATE means the work already exists. Treating it as a failure and retrying is the most common way integrations end up creating confusion for the customer.