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

# Errors

> Status codes, error bodies and error codes of the Hyperstack API.

## Error body

Most errors have this body:

```json theme={null}
{
  "success": false,
  "error": "Group Not Found",
  "error_code": "group_not_found"
}
```

* `error` is a message for people. It can change.
* `error_code` is for your code. Use it to decide what to do.

A missing or wrong API key has a different body, with a single `detail` field:

```json theme={null}
{
  "detail": "Invalid token or organization not found"
}
```

> [!NOTE]
>
> A few errors come with status `200`: the webhook and recipient endpoints, and any unknown action in a URL (such as `/v1/groups/foo`, which returns `{"success": false}`). Always check `success` as well as the status code.

## Status codes

| Status | Meaning |
| - | - |
| `200` | The request was handled. Check `success` in the body. |
| `400` | A parameter is missing or not valid. See `error_code`. |
| `401` | [Platform Status](/docs/api-guide/platform-status) only: the API key you sent is not valid. |
| `402` | Your organization has no credits left to issue credentials. |
| `403` | The API key is missing, wrong or revoked. |
| `404` | The group, credential or path does not exist in your organization. |
| `405` | The HTTP method is not allowed. [Platform Status](/docs/api-guide/platform-status) accepts `GET` only. |
| `409` | The recipient already has a credential in this group. |
| `500` | Something went wrong on our side. The body is an HTML page, not JSON. |

## Authentication errors

| Status | Body |
| - | - |
| `403` | `{"detail": "Authentication credentials were not provided."}`: no `Authorization` header. |
| `403` | `{"detail": "Invalid token or organization not found"}`: the key is wrong or was revoked. |

## Error codes

| Error code | Status | Endpoints | What to do |
| - | - | - | - |
| `missing_title_description` | 400 | [Create Credential Group](/docs/api-guide/create-credential-group) | Send both `title` and `description`. |
| `missing_templates` | 400 | [Create Credential Group](/docs/api-guide/create-credential-group) | Send `badge_template`, `certificate_template` or both. |
| `invalid_badge_template` | 400 | [Create](/docs/api-guide/create-credential-group) and [Update Credential Group](/docs/api-guide/update-credential-group) | Send the key of a badge design in your organization. |
| `invalid_certificate_template` | 400 | [Create](/docs/api-guide/create-credential-group) and [Update Credential Group](/docs/api-guide/update-credential-group) | Send the key of a certificate design in your organization. |
| `invalid_tags` | 400 | [Create](/docs/api-guide/create-credential-group) and [Update Credential Group](/docs/api-guide/update-credential-group) | Send `tags` as a list of strings or a comma-separated string. |
| `invalid_group_code` | 400 | [Create](/docs/api-guide/create-credential-group) and [Update Credential Group](/docs/api-guide/update-credential-group) | Send `group_code` as text of 50 characters or fewer. |
| `not_found` | 404 | [View](/docs/api-guide/view-credential-group) and [Update Credential Group](/docs/api-guide/update-credential-group) | Check the group key. |
| `missing_recipient` | 400 | [Issue](/docs/api-guide/create-credential) and [Generate Credential](/docs/api-guide/generate-credential) | Send `recipient.name` and `recipient.email`. |
| `invalid_recipient` | 400 | [Issue](/docs/api-guide/create-credential), [Generate](/docs/api-guide/generate-credential) and [Search Credentials](/docs/api-guide/search-credentials) | Send `recipient` as an object. |
| `invalid_email` | 400 | [Issue](/docs/api-guide/create-credential) and [Generate Credential](/docs/api-guide/generate-credential) | Send a valid `recipient.email`. |
| `invalid_custom_attributes` | 400 | [Issue](/docs/api-guide/create-credential), [Generate Credential](/docs/api-guide/generate-credential) and [Update Recipient](/docs/api-guide/update-recipient) | Send `custom_attributes` as an object. |
| `group_not_found` | 404 | [Issue](/docs/api-guide/create-credential), [Generate Credential](/docs/api-guide/generate-credential), [Credential Activity](/docs/api-guide/credential-activity) | Check the group key. |
| `credential_exists` | 409 | [Issue](/docs/api-guide/create-credential) and [Generate Credential](/docs/api-guide/generate-credential) | The recipient already has a credential in this group. To allow more than one, change the group's settings in the Studio. |
| `low_balance` | 402 | [Issue](/docs/api-guide/create-credential) and [Generate Credential](/docs/api-guide/generate-credential) | Buy more credits. |
| `invalid_expiry` | 400 | [Update Credential](/docs/api-guide/update-credential) | Send `expiry` as a Unix timestamp in seconds. |
| `invalid_status` | 400 | [Publish Credential](/docs/api-guide/publish-credential) | Only draft credentials can be published. |
| `invalid_date` | 400 | [Search Credentials](/docs/api-guide/search-credentials), [Credential Activity](/docs/api-guide/credential-activity) | Check the date format of that endpoint. |
| `range_too_large` | 400 | [Credential Activity](/docs/api-guide/credential-activity) | Ask for 31 days or fewer. |
| `invalid_event` | 400 | [Credential Activity](/docs/api-guide/credential-activity) | Use only `view`, `share`, `download` and `click`. |
| `invalid_page` | 400 | [List](/docs/api-guide/list-credentials) and [Search Credentials](/docs/api-guide/search-credentials), [List](/docs/api-guide/list-groups) and [Search Groups](/docs/api-guide/search-groups), [Credential Activity](/docs/api-guide/credential-activity) | Send `page` and `page_size` as whole numbers, `page` 1 or more. Credential Activity takes `page_size` from 1 to 500; the list and search endpoints cut a bigger `page_size` to 500. |
| `credential_not_found` | 404 | [Credential Activity](/docs/api-guide/credential-activity) | Check the credential key, and that it is in the group you sent. |
| `invalid_token` | 401 | [Platform Status](/docs/api-guide/platform-status) | Check the API key, or send no key. |
| `recipient_not_found` | 200 | [Update Recipient](/docs/api-guide/update-recipient) | No recipient has this email in your organization. |
| `missing_url_event` | 200 | [Subscribe to Webhook](/docs/api-guide/webhook-subscribe) | Send `url` and a list of `events`. |
| `invalid_event` | 200 | [Subscribe to Webhook](/docs/api-guide/webhook-subscribe) | Use only `credential.issued`. |
| `invalid_url` | 200 | [Subscribe to Webhook](/docs/api-guide/webhook-subscribe) | The URL must start with `http://` or `https://`. |
| `invalid_action` | 200 | `/v1/webhook/{action}` | Use `subscribe` or `unsubscribe`. |

## Credential not found

[View](/docs/api-guide/view-credential), [Update](/docs/api-guide/update-credential) and [Publish Credential](/docs/api-guide/publish-credential) return `404` with no `error_code` when the credential is not in your organization:

```json theme={null}
{
  "success": false,
  "error": "Document does not exists in your account"
}
```


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