Skip to main content

​
Error Response Format

All error responses follow this structure: 
{
  "error": {
    "message": "Descriptive error message explaining what went wrong",
    "code": 400
  }
}

​
HTTP Status Codes

CodeStatusDescription
200OKRequest completed successfully
201CreatedNew resource created successfully
400Bad RequestValidation error or bad request data
402Payment RequiredInsufficient transcription minutes
403ForbiddenInvalid or missing API key
404Not FoundResource or endpoint not found
429Too Many RequestsRate limit or monthly quota exceeded
500Internal Server ErrorUnexpected error on Heify’s servers

​
400 Bad Request

The request is malformed or contains invalid parameters.
Error: "Missing required field: configuration_id"Ensure all required parameters are included in the request body.
{
  "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
Error: "Invalid JSON format"Validate your JSON before sending. Common issues:
  • Missing commas between fields
  • Trailing commas after the last field
  • Unescaped quotes inside string values
Error: "Maximum of 20 configurations per client exceeded"Delete unused resources before creating new ones. See Rate Limits & Quotas for all limits.
Error: "Unsupported audio format"Ensure your file meets the requirements:
  • Supported formats: AAC, AIFF, AMR, ASF, FLAC, MP3, OGG, WAV, WebM, M4A, MP4
  • Max size: 200 MB
  • Max duration: 2 hours (7200 seconds)
Error: "Invalid group value"Use only the allowed group values when updating a transcription:
  • PENDING_REVIEW
  • UNDER_REVIEW
  • ARCHIVED
  • "" (empty string to remove the group)

​
402 Payment Required

Your account has run out of transcription minutes. Submit operations on transcriptions will be rejected until your balance is topped up. Contact hola@heify.com to add more minutes.

​
403 Forbidden

Authentication failed. Your API key is invalid, missing, or inactive.
CauseSolution
Missing x-api-key headerAdd the header to every request
Invalid API key valueVerify the key in your dashboard
Deactivated API keyGenerate a new key
Wrong header nameUse x-api-key, not Authorization

​
404 Not Found

The requested resource or endpoint does not exist.
CauseSolution
Typo in the endpoint URLDouble-check the path against the API reference
Resource ID does not existVerify the ID belongs to your account
Using GET instead of POSTAll Heify endpoints use POST
Wrong base URLUse https://api.heify.com/

​
429 Too Many Requests

You have exceeded the rate limit for an endpoint or reached a monthly quota. See Rate Limits & Quotas for per-endpoint limits and a backoff implementation example.

​
500 Internal Server Error

An unexpected error occurred on Heify’s servers.
1

Retry the request

The error is likely temporary. Wait a few seconds and try again.
2

Contact support

If the issue persists, contact hola@heify.com.