Error Handling

The Heify API uses standard HTTP status codes to indicate the success or failure of requests. This guide explains how to handle errors effectively.

HTTP Status Codes

Status Code	Meaning	Description
`200 OK`	Success	Request completed successfully
`201 Created`	Resource Created	New resource created successfully (e.g., configuration)
`400 Bad Request`	Client Error	Invalid request format or parameters
`403 Forbidden`	Authentication Failed	Invalid or missing API key
`404 Not Found`	Resource Not Found	Requested resource doesn’t exist
`429 Too Many Requests`	Rate Limit Exceeded	Too many requests in a short period
`500 Internal Server Error`	Server Error	Unexpected error on Heify servers

Error Response Format

All error responses follow a consistent JSON structure:

{
  "message": "Descriptive error message explaining what went wrong"
}

Example Error Response

{
  "message": "Configuration not found or does not belong to your account"
}

Common Errors by Status Code

400 Bad Request

The most common error type. Occurs when the request is malformed or contains invalid parameters.

Common Causes

Missing required fields

Error: "Missing required field: configuration_id"Solution: Ensure all required parameters are included in the request body.

{
  "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Invalid JSON format

Error: "Invalid JSON format"Solution: Validate your JSON before sending. Common issues:

Missing commas between fields
Trailing commas
Unescaped quotes in strings

Use a JSON validator or library to ensure correctness.

Resource not found

Error: "Configuration not found"Solution: Verify the resource ID exists and belongs to your account:

curl -X POST https://api.heify.com/get-configurations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{}'

Invalid audio format

Error: "Unsupported audio format"Solution: Ensure your audio file is in a supported format:

Supported: aac, aiff, amr, asf, flac, mp3, ogg, wav, webm, m4a, mp4
Max size: 200 MB
Max duration: 2 hours (7200 seconds)

Invalid group value

Error: "Invalid group value"Solution: Use only allowed group values:

PENDING_REVIEW
UNDER_REVIEW
ARCHIVED
"" (empty string to remove group)

Exceeded configuration limit

Error: "Maximum of 20 configurations per client exceeded"Solution: Delete unused configurations before creating new ones:

curl -X POST https://api.heify.com/delete-configuration \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "old-config-id"
  }'

Solutions

Verify account status

Check your account status and available resources in your Heify Dashboard

Contact support

If you believe this is an error, contact Heify support for assistance

403 Forbidden

Authentication failed. Your API key is invalid, missing, or inactive.

Common Causes

Cause	Solution
Missing `x-api-key` header	Add the header to your request
Invalid API key	Verify the key in your dashboard
Deactivated API key	Generate a new key
Wrong header name	Use `x-api-key`, not `Authorization`

Example Fix

curl -X POST https://api.heify.com/details \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"  # Wrong header

404 Not Found

The requested resource doesn’t exist or the endpoint URL is incorrect.

Error Example

{
  "message": "Endpoint not found"
}

Common Causes

Typo in endpoint URL
Using GET instead of POST
Incorrect base URL

Solution

Verify the endpoint:

Correct	Incorrect
`POST https://api.heify.com/details`	`GET https://api.heify.com/details`
`POST https://api.heify.com/submit`	`POST https://api.heify.com/submits`

429 Too Many Requests

You’ve exceeded the rate limit for the endpoint.

Solutions

Implement exponential backoff

Python

import time

def request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = func()
            
            if response.status_code == 429:
                # Exponential backoff
                wait_time = (2 ** attempt) * 5  # 5, 10, 20 seconds
                print(f"Rate limited. Waiting {wait_time} seconds...")
                time.sleep(wait_time)
                continue
            
            return response
            
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(5)
    
    raise Exception("Max retries exceeded")

Respect rate limits

See the Rate Limits documentation for endpoint-specific limits.

500 Internal Server Error

An unexpected error occurred on Heify’s servers.

What to Do

Retry the request

The error may be temporary. Wait a few seconds and try again.

Contact support

If the issue persists, contact hola@heify.com or in the contact page.

Next Steps

Authentication

Learn how to authenticate your API requests

API Reference

Explore endpoint documentation

Getting Started

Core Concepts

Error Handling

Error Handling

HTTP Status Codes

Error Response Format

Example Error Response

Common Errors by Status Code

400 Bad Request

Common Causes

Solutions

403 Forbidden

Common Causes

Example Fix

404 Not Found

Error Example

Common Causes

Solution

429 Too Many Requests

Solutions

500 Internal Server Error

What to Do

Next Steps

Authentication

API Reference

Getting Started

Core Concepts

​Error Handling

​HTTP Status Codes

​Error Response Format

​Example Error Response

​Common Errors by Status Code

​400 Bad Request

​Common Causes

​Solutions

​403 Forbidden

​Common Causes

​Example Fix

​404 Not Found

​Error Example

​Common Causes

​Solution

​429 Too Many Requests

​Solutions

​500 Internal Server Error

​What to Do

​Next Steps

Authentication

API Reference

Error Handling

HTTP Status Codes

Error Response Format

Example Error Response

Common Errors by Status Code

400 Bad Request

Common Causes

Solutions

403 Forbidden

Common Causes

Example Fix

404 Not Found

Error Example

Common Causes

Solution

429 Too Many Requests

Solutions

500 Internal Server Error

What to Do

Next Steps