Error Handling

Response envelope, error codes, idempotency, and circuit breaker behavior.

Every PlatformXe API response uses a consistent envelope format, making it straightforward to handle success and failure in a uniform way.

Response envelope

Success

{
  "success": true,
  "data": {
    "messageId": "msg_abc123def456",
    "status": "queued"
  }
}

Error

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Field 'to' is required and must be a non-empty array."
  }
}

Always check the success field first. When success is false, the error object contains a machine-readable code and a human-readable message.

Common error codes

Code	HTTP Status	Description
BAD_REQUEST	400	Invalid request body, missing required fields
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	API key lacks the required scope
NOT_FOUND	404	Resource does not exist
RATE_LIMITED	429	Rate limit exceeded — check the Retry-After header
INTERNAL_ERROR	500	Unexpected server error

Permission-specific error codes

These codes are returned by the Authorization Engine:

Code	Description
ROLE_NOT_FOUND	The specified role does not exist
CAPABILITY_INVALID	The capability string is malformed or not recognized
MODULE_LIMIT_EXCEEDED	The organization has reached its module limit for the current plan
POLICY_CONFLICT	A resource policy conflicts with an existing policy
RELATIONSHIP_CYCLE	The ReBAC relationship would create a cycle in the graph
FEDERATION_NOT_ALLOWED	Federation features require an Enterprise plan

Idempotency

For mutation endpoints (POST, PATCH, DELETE), you can pass an idempotency key to safely retry requests:

curl -X POST https://api.platformxe.com/api/v1/messaging/email/send \
  -H "x-api-key: pxk_live_your_key" \
  -H "x-idempotency-key: unique-request-id-abc123" \
  -H "Content-Type: application/json" \
  -d '{ "to": [{ "email": "jane@example.com" }], "subject": "Hello", "html": "<p>Hi</p>" }'

If the same x-idempotency-key is sent within a 24-hour window, the API returns the original response without re-executing the operation.

Circuit breaker (SDK)

The TypeScript SDK includes a built-in circuit breaker for permission checks:

1. Closed (normal) — requests flow through as usual.
2. Open — after repeated failures, the circuit opens and requests fail immediately (or return allowed: true if failOpen is enabled).
3. Half-open — after a cooldown period, the SDK sends a test request. If it succeeds, the circuit closes again.

const px = new PlatformXe({
  apiKey: 'pxk_live_your_key',
  failOpen: false,  // default: deny access when circuit is open
});