> ## 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.                                                                                                                                    |
| `VALIDATION_STEP_NOT_APPLICABLE`  | 400  | You called an activation step that does not apply to this provider (e.g., uploading documents for a provider whose activation sequence does not include an `upload` step). `details.expectedSteps` lists the real sequence for the provider. |
| `RESOURCE_NOT_FOUND`              | 404  | The app, provider, or workflow does not exist in this workspace.                                                                                                                                                                             |
| `RESOURCE_CONFLICT`               | 409  | The resource already exists or is in a state that prevents this action (e.g., resubmitting an already-approved activation form).                                                                                                             |
| `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.