Errors - Hyperstack API Docs

Error body

Most errors have this body:

{
  "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:

{
  "detail": "Invalid token or organization not found"
}

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 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 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	Send both `title` and `description`.
`missing_templates`	400	Create Credential Group	Send `badge_template`, `certificate_template` or both.
`invalid_badge_template`	400	Create and Update Credential Group	Send the key of a badge design in your organization.
`invalid_certificate_template`	400	Create and Update Credential Group	Send the key of a certificate design in your organization.
`invalid_tags`	400	Create and Update Credential Group	Send `tags` as a list of strings or a comma-separated string.
`invalid_group_code`	400	Create and Update Credential Group	Send `group_code` as text of 50 characters or fewer.
`not_found`	404	View and Update Credential Group	Check the group key.
`missing_recipient`	400	Issue and Generate Credential	Send `recipient.name` and `recipient.email`.
`invalid_recipient`	400	Issue, Generate and Search Credentials	Send `recipient` as an object.
`invalid_email`	400	Issue and Generate Credential	Send a valid `recipient.email`.
`invalid_custom_attributes`	400	Issue, Generate Credential and Update Recipient	Send `custom_attributes` as an object.
`group_not_found`	404	Issue, Generate Credential, Credential Activity	Check the group key.
`credential_exists`	409	Issue and 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 and Generate Credential	Buy more credits.
`invalid_expiry`	400	Update Credential	Send `expiry` as a Unix timestamp in seconds.
`invalid_status`	400	Publish Credential	Only draft credentials can be published.
`invalid_date`	400	Search Credentials, Credential Activity	Check the date format of that endpoint.
`range_too_large`	400	Credential Activity	Ask for 31 days or fewer.
`invalid_event`	400	Credential Activity	Use only `view`, `share`, `download` and `click`.
`invalid_page`	400	List and Search Credentials, List and Search Groups, 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	Check the credential key, and that it is in the group you sent.
`invalid_token`	401	Platform Status	Check the API key, or send no key.
`recipient_not_found`	200	Update Recipient	No recipient has this email in your organization.
`missing_url_event`	200	Subscribe to Webhook	Send `url` and a list of `events`.
`invalid_event`	200	Subscribe to Webhook	Use only `credential.issued`.
`invalid_url`	200	Subscribe to Webhook	The URL must start with `http://` or `https://`.
`invalid_action`	200	`/v1/webhook/{action}`	Use `subscribe` or `unsubscribe`.

Credential not found

View, Update and Publish Credential return 404 with no error_code when the credential is not in your organization:

{
  "success": false,
  "error": "Document does not exists in your account"
}

Last modified on October 20, 2026