Errors

Sellfern public V1 errors use stable machine-readable codes so integrations and AI agents can recover safely.

Status	Code	Meaning	Recommended handling
`400`	`validation_error`	Request parameters or body are invalid.	Fix the request before retrying.
`401`	`unauthorized`	API key is missing, invalid, expired, or revoked.	Stop and ask for a valid API key.
`403`	`missing_scope`	API key lacks the required scope.	Request a key with the minimum additional scope.
`404`	`not_found`	Resource does not exist or is outside the API key organization.	Do not infer cross-organization ownership.
`422`	`idempotency_conflict`	Idempotency key was reused with a different request.	Generate a new key for a new logical mutation.
`429`	`rate_limited`	API key exceeded rate limits.	Back off and retry later.

Error response shape

error.details is included when structured remediation data is available. meta.request_id is always safe to log and share with Sellfern support.

{
  "success": false,
  "error": {
    "code": "missing_scope",
    "message": "API key lacks the required scope for this endpoint.",
    "details": {
      "required_scope": "orders:read"
    }
  },
  "meta": {
    "request_id": "req_01HX..."
  }
}

Developer Guides

Integrations

Error response shape