Errors

All Workspace API errors use this envelope:

{
  "error": {
    "code": "VALIDATION_MISSING_PARAMETER",
    "message": "Required parameter 'contactEmail' is missing",
    "details": { "parameter": "contactEmail" }
  },
  "request_id": "228aaefb-3ce2-4dd0-a73b-b96f71c5779f"
}

error.code — machine-readable SCREAMING_SNAKE_CASE identifier. Stable across releases; safe to switch on.
error.message — human-readable description. May change; do not switch on it.
error.details — optional structured context (e.g., which field failed, allowed values).
request_id — UUID for this specific request. Include it when contacting support.

Common error codes

Code	HTTP	When you see it
`AUTH_INVALID_CREDENTIALS`	401	Wrong API key, or using Bearer token where Basic auth is required (or vice versa).
`AUTH_FORBIDDEN`	403	The API key is valid but lacks permission for this resource.
`VALIDATION_MISSING_PARAMETER`	400	A required field was omitted from the request body. `details.parameter` names the field.
`VALIDATION_INVALID_PARAMETER`	400	A field was present but its value or type is invalid. `details.parameter` + `details.value` give context.
`RESOURCE_NOT_FOUND`	404	The app, provider, or workflow does not exist in this workspace.
`RESOURCE_CONFLICT`	409	The resource is in a state that prevents this action (e.g., submitting activation for a provider whose existing ticket is currently `activation_processing`, or losing the optimistic-concurrency race on concurrent submits for the same provider — retry).
`SYSTEM_INTERNAL_ERROR`	500	Unexpected server error. Retry with exponential back-off; if persistent, contact support with the `request_id`.
`IDEMPOTENCY_KEY_CONFLICT`	409	You reused an `Idempotency-Key` header with a different request body. Use a new key for a new request.
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	409	An earlier request with the same `Idempotency-Key` is still executing. Retry after it completes.

Authentication errors (401)

The most common AUTH_INVALID_CREDENTIALS cause is using the wrong auth scheme. See the Authentication guide for which credentials apply to which surface.

Overview

Workspace

Apps

Providers

Provider Activation

Redirect URIs

Webhooks

Custom Domain

Workflows

Production Tests

Common error codes

Authentication errors (401)

​Common error codes

​Authentication errors (401)

Common error codes

Authentication errors (401)