API Documentation
Try Demo Home
Reference

Handle errors gracefully

Every error from the Sigma PIM API follows a consistent JSON shape. Use the error code for programmatic handling and the message for debugging and user-facing display.

Error Response Shape

All error responses return a JSON object with two fields: a machine-readable error code and a human-readable message.

{ "error": "ERROR_CODE", "message": "Human-readable description of what went wrong" }

error

A stable, uppercase string constant. Use this for programmatic error handling in your code. These codes will not change between API versions.

message

A human-readable description that may change over time. Suitable for logging and debugging, but do not parse or match against this field programmatically.

Always check the HTTP status code first for broad categorization (4xx = client error, 5xx = server error), then use the error field for specific handling.

Error Codes

400

VALIDATION_ERROR

The request body contains invalid data, is missing required fields, or fails schema validation. Check the message for details about which field is invalid.

// Missing required field { "error": "VALIDATION_ERROR", "message": "Email and password are required" } // Invalid attribute value type { "error": "VALIDATION_ERROR", "message": "Attribute 'price' expects type 'number', got 'string'" } // Pattern validation failure { "error": "VALIDATION_ERROR", "message": "Value for 'sku' does not match pattern '^[A-Z]{2}-\\d{3}$'" }
401

UNAUTHORIZED

The request is missing authentication credentials or the provided credentials are invalid. This includes expired JWT tokens, invalid API keys, and missing auth headers.

// Missing authentication header { "error": "UNAUTHORIZED", "message": "Missing authentication" } // Invalid or expired JWT token { "error": "UNAUTHORIZED", "message": "Invalid or expired token" } // Invalid API key { "error": "UNAUTHORIZED", "message": "Invalid API key" }
403

PERMISSION_DENIED

The authenticated user does not have permission to perform the requested action. This is determined by the user's role and its attribute-level permissions.

{ "error": "PERMISSION_DENIED", "message": "Permission denied" }
404

NOT_FOUND

The requested resource does not exist. The message includes the resource type and the ID that was requested, making it easy to identify the missing entity.

// Record not found { "error": "NOT_FOUND", "message": "Entity 'ent-abc123' not found" } // Schema not found { "error": "NOT_FOUND", "message": "Schema 'schema-xyz' not found" } // Catalog not found { "error": "NOT_FOUND", "message": "Catalog 'cat-456' not found" }
409

CONFLICT

The request conflicts with the current state of the resource. This commonly occurs when creating a resource with a duplicate ID or violating a unique constraint on an attribute value.

// Duplicate ID { "error": "CONFLICT", "message": "Entity with id 'ent-abc123' already exists" } // Unique constraint violation { "error": "CONFLICT", "message": "Value 'CW-001' for attribute 'sku' must be unique" }
403

LIMIT_EXCEEDED

The Early Access edition enforces a 500 SKU limit per workspace. This error occurs when attempting to create a new record that would exceed the limit. Delete unused records or upgrade to increase the limit.

{ "error": "LIMIT_EXCEEDED", "message": "Entity limit of 500 reached" }
400

TRANSITION_ERROR

A lifecycle state transition was rejected. This can happen when the transition is not defined in the workflow, the user's role lacks permission to perform it, or the record does not meet the minimum completeness score required by the transition gate.

// Invalid transition { "error": "TRANSITION_ERROR", "message": "Transition from 'draft' to 'published' is not allowed" } // Completeness gate not met { "error": "TRANSITION_ERROR", "message": "Completeness score 65% does not meet minimum 80% for transition to 'review'" }
500

INTERNAL_ERROR

An unexpected server error occurred. The message will always be generic for security reasons. If you encounter this error repeatedly, contact support with the request details and timestamp.

{ "error": "INTERNAL_ERROR", "message": "Internal server error" }

Error Code Summary

HTTP Status Error Code Description
400 VALIDATION_ERROR Invalid input data, missing required fields, type mismatch, or pattern violation
400 TRANSITION_ERROR Lifecycle transition not allowed, role gate or completeness gate failed
401 UNAUTHORIZED Missing or invalid authentication credentials
403 PERMISSION_DENIED Authenticated but insufficient permissions for the action
403 LIMIT_EXCEEDED Early Access 500 SKU limit reached
404 NOT_FOUND Requested entity or resource does not exist
409 CONFLICT Duplicate ID or unique constraint violation
500 INTERNAL_ERROR Unexpected server error

Handling Errors in Code

// JavaScript example: robust error handling async function createRecord(token, data) { const res = await fetch("https://api.sigma-pim.com/api/v1/records", { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify(data), }); if (!res.ok) { const err = await res.json(); switch (err.error) { case "VALIDATION_ERROR": console.error("Invalid data:", err.message); break; case "UNAUTHORIZED": // Token expired — refresh and retry break; case "LIMIT_EXCEEDED": console.error("SKU limit reached"); break; case "CONFLICT": console.error("Duplicate:", err.message); break; default: console.error("API error:", err.error, err.message); } throw new Error(err.message); } return res.json(); }

Troubleshooting

"Missing authentication" on every request

Ensure you are including either the Authorization: Bearer {token} header or the X-Sigma-ApiKey: {key} header. The auth routes (/api/v1/auth/*) and the health check (/healthz) are the only endpoints that do not require authentication.

"Invalid or expired token" after successful login

JWT tokens expire after 24 hours. Call POST /api/v1/auth/refresh with the current token before it expires. If the token has already expired, you must re-authenticate via POST /api/v1/auth/login.

"Entity limit of 500 reached"

The Early Access edition enforces a 500 SKU limit per workspace. Delete unused records to free up capacity, or contact us about upgrading your plan for higher limits.

"Transition from X to Y is not allowed"

Check that the workflow attached to the record's schema defines a valid transition between those two states. Also verify that your role has permission for the transition and that the record meets any completeness gates defined on the transition.

"Entity with id X already exists"

When creating resources, the API auto-generates unique IDs. If you are providing a custom id field, ensure it is unique. Use a different ID or omit it to let the system generate one.

Receiving 500 INTERNAL_ERROR repeatedly

This indicates an unexpected server issue. Note the exact request (method, URL, body) and timestamp, then contact support. Check GET /healthz to verify the API server is running.

Rate Limiting

The Early Access edition does not enforce rate limits. However, production deployments may introduce rate limiting in the future. When rate limiting is active, the API will return:

// 429 Too Many Requests (future) { "error": "RATE_LIMITED", "message": "Too many requests. Retry after 60 seconds." }
When rate limiting is introduced, responses will include Retry-After and X-RateLimit-Remaining headers. Design your integration to respect these headers by implementing exponential backoff.
Previous Webhooks