Errors - Stockly

All errors share one shape:

{
  "error": {
    "code": "conflict",
    "message": "idempotencyKey was already used with a different payload",
    "details": { "idempotencyKey": "order-1001-reward" },
    "requestId": "f0e1d2c3-4b5a-6789-0abc-def012345678"
  }
}

code — a stable machine-readable code (see below).
message — human-readable explanation.
details — optional structured context. For validation failures (bad_request) this contains the specific field issues.
requestId — correlation id, also returned in the x-request-id header. Include it when contacting support.

Status codes

HTTP	`code`	Meaning
400	`bad_request`	Malformed JSON or failed validation (`details` lists the issues).
401	`unauthorized`	Missing or invalid `x-api-key`.
403	`forbidden`	Authenticated but not permitted.
404	`not_found`	Resource doesn’t exist (or belongs to another app).
409	`conflict`	Uniqueness conflict — duplicate email/externalId, or idempotency-key reuse.
422	`unprocessable_entity`	Semantically invalid request.
500	`internal_error`	Unexpected server error.
502	`upstream_error`	An upstream dependency failed.

Branch on error.code, not the HTTP status or message text — codes are stable, messages may change.

​Status codes

Status codes