> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope and error codes for Workspace API responses.

All Workspace API errors use this envelope:

```json theme={null}
{
  "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](/api-reference/authentication) for which credentials apply to which surface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.