Errors and request IDs
The error envelope every Nexra API returns, what each status code means and how to report a problem with a request ID.
Updated 07/10/2026
Error envelope
Every error from the platform API has the same shape:
{
"error": "request_failed",
"message": "Workspace permission is required: connect.flow.publish",
"statusCode": 403,
"requestId": "6f1c2a8e-4b1d-4c55-9a0e-3d7f2b9c1e40",
"path": "/api/console/connect/flows/flow_123/publish",
"method": "POST"
}error is request_failed for 4xx errors and internal_server_error for 5xx.
message is safe to show to users. When several validation problems occur, they are joined with commas.
Sensitive values are redacted from every error before it is returned.
Request IDs
Every response carries an X-Request-ID header, and errors repeat it as requestId. Send your own X-Request-ID to correlate Nexra's logs with yours. Include the request ID whenever you contact support.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | The request body or parameters are invalid | Fix the request; the message names the problem |
401 | Missing, expired or invalid credentials | Sign in again or send a valid token |
403 | Authenticated but not allowed: wrong workspace, missing permission, archived application or a production gate | Check your role, workspace and approvals |
404 | The resource does not exist in this workspace | Check the ID and X-Workspace-Id |
405 | Method not supported (for example GET /mcp) | Use the documented method |
409 | Conflict: duplicate name or slug, idempotency key reused differently, immutable published version, self-approval | Change the request or use a new version |
429 | Rate limit exceeded | Wait retryAfterSeconds, then retry; see Rate limits |
500 | Unexpected server error | Retry with backoff and report the request ID |
503 | A required service is not configured or available | Retry later |
Connector errors
Errors from providers in Nexra Connect are normalised into a category before they reach you:
| Category | Retried automatically |
|---|---|
authentication | No: rotate the connection's credentials |
permission | No: grant the provider scope |
not_found | No |
validation | No: fix the mapping or data |
rate_limit | Yes, with backoff, honouring Retry-After |
provider | Yes for safe operations; uncertain writes go to the dead-letter queue |
timeout | Reported with the provider's job or statement handle where available |
MCP errors
MCP uses JSON-RPC error codes. See Use the Nexra MCP server.
Agentic commerce errors
The agentic commerce API returns its own codes: INVALID_INPUT (400), AUTHENTICATION_FAILED (401), UNAUTHORIZED_CAPABILITY (403), DATA_UNAVAILABLE (404), DUPLICATE_CONFLICT (409), EXECUTION_FAILED (500) and DEPENDENCY_UNAVAILABLE (503).