Error Codes

Complete reference for API error responses and troubleshooting.

Error Response Format

All errors follow this consistent structure:

{
  "error": "Error Type",
  "message": "Human-readable error description",
  "error_code": "MACHINE_READABLE_CODE",
  "details": {
    "field_name": "Specific error details"
  }
}

HTTP Status Codes

Code	Status	Meaning	Action
200	OK	Request successful	Continue
201	Created	Resource created	Continue
204	No Content	Successful deletion	Continue
400	Bad Request	Invalid request parameters	Fix request
401	Unauthorized	Missing/invalid API key	Check authentication
402	Payment Required	Quota exceeded	Upgrade plan
403	Forbidden	Insufficient permissions	Check permissions
404	Not Found	Resource doesn't exist	Check resource ID
409	Conflict	Resource state conflict	Check resource state
413	Payload Too Large	File size exceeded	Reduce file size
422	Unprocessable Entity	Validation failed	Fix input data
429	Too Many Requests	Rate limit exceeded	Implement backoff
500	Internal Server Error	Server error	Retry, contact support
503	Service Unavailable	Temporary maintenance	Retry later

Common Errors

Authentication Errors (401)

Missing API Key

{
  "error": "Unauthorized",
  "message": "Missing API key",
  "error_code": "MISSING_API_KEY"
}

Cause: No Authorization header provided.

Solution: Include Authorization: Bearer YOUR_API_KEY header.

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "error_code": "INVALID_API_KEY"
}

Causes:

• Typo in API key
• Key has been revoked
• Using wrong environment key (test vs live)

Solution: Verify API key in dashboard.

Key Revoked

{
  "error": "Unauthorized",
  "message": "API key has been revoked",
  "error_code": "KEY_REVOKED"
}

Solution: Create new API key.

Validation Errors (400, 422)

Invalid Parameters

{
  "error": "Validation Error",
  "message": "Invalid field values",
  "details": {
    "language": "Language 'xx' is not supported",
    "name": "Name cannot be empty"
  }
}

Solution: Check details object for field-specific errors.

Missing Required Field

{
  "error": "Bad Request",
  "message": "Missing required field: audio_file",
  "error_code": "MISSING_FIELD"
}

Solution: Include all required fields.

Resource Errors (404)

Resource Not Found

{
  "error": "Not Found",
  "message": "Document not found",
  "error_code": "DOCUMENT_NOT_FOUND"
}

Causes:

• Invalid resource ID
• Resource deleted
• Resource belongs to different organization

Solution: Verify resource ID exists.

Rate Limit Errors (429)

Rate Limit Exceeded

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please try again in 60 seconds.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

Solution:

• Wait retry_after seconds
• Implement exponential backoff
• Upgrade plan for higher limits

See Rate Limits.

Quota Errors (402)

Quota Exceeded

{
  "error": "Quota Exceeded",
  "message": "Monthly transcription quota exceeded",
  "error_code": "QUOTA_EXCEEDED",
  "details": {
    "quota_limit": 100,
    "quota_used": 100,
    "quota_unit": "hours"
  }
}

Solution: Upgrade plan or wait for quota reset.

Storage Limit

{
  "error": "Storage Limit Exceeded",
  "message": "Storage quota exceeded for your plan",
  "error_code": "STORAGE_EXCEEDED",
  "details": {
    "storage_used_gb": 50,
    "storage_limit_gb": 50
  }
}

Solution: Delete old documents or upgrade plan.

File Upload Errors (413, 400)

File Too Large

{
  "error": "Payload Too Large",
  "message": "Audio file exceeds maximum size",
  "error_code": "FILE_TOO_LARGE",
  "details": {
    "max_size_mb": 500,
    "file_size_mb": 650
  }
}

Solution: Split file or use TUS upload for large files.

Unsupported Format

{
  "error": "Bad Request",
  "message": "Unsupported audio format",
  "error_code": "UNSUPPORTED_FORMAT",
  "details": {
    "supported_formats": ["mp3", "wav", "flac", "m4a", "aac", "ogg"]
  }
}

Solution: Convert to supported format.

Corrupted File

{
  "error": "Bad Request",
  "message": "File is corrupted or invalid",
  "error_code": "INVALID_FILE"
}

Solution: Re-encode or re-export file.

State Conflict Errors (409)

Resource In Use

{
  "error": "Conflict",
  "message": "Cannot delete model: currently in use",
  "error_code": "MODEL_IN_USE",
  "details": {
    "active_transcriptions": 3
  }
}

Solution: Wait for active operations to complete.

Invalid State Transition

{
  "error": "Conflict",
  "message": "Cannot start training: model not ready",
  "error_code": "MODEL_NOT_READY",
  "details": {
    "current_status": 1,
    "required_status": 2
  }
}

Solution: Complete prerequisite steps first.

Error Code Reference

Authentication (AUTH_*)

Code	HTTP	Description
MISSING_API_KEY	401	No Authorization header
INVALID_API_KEY	401	Invalid/unknown API key
KEY_REVOKED	401	API key revoked
KEY_EXPIRED	401	API key expired
INSUFFICIENT_PERMISSIONS	403	Key lacks permissions

Validation (VALIDATION_*)

Code	HTTP	Description
MISSING_FIELD	400	Required field missing
INVALID_FORMAT	400	Invalid field format
UNSUPPORTED_LANGUAGE	400	Language not supported
UNSUPPORTED_FORMAT	400	File format not supported

Resources (*_NOT_FOUND)

Code	HTTP	Description
DOCUMENT_NOT_FOUND	404	Document doesn't exist
MODEL_NOT_FOUND	404	Custom model doesn't exist
GLOSSARY_NOT_FOUND	404	Glossary doesn't exist
SESSION_NOT_FOUND	404	Real-time session doesn't exist

Quotas (QUOTA_*, *_EXCEEDED)

Code	HTTP	Description
QUOTA_EXCEEDED	402	Monthly quota exceeded
STORAGE_EXCEEDED	402	Storage limit exceeded
MODEL_LIMIT_EXCEEDED	402	Custom model limit reached
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded

Files (FILE_*)

Code	HTTP	Description
FILE_TOO_LARGE	413	File exceeds size limit
INVALID_FILE	400	Corrupted/invalid file
UNSUPPORTED_CODEC	400	Audio codec not supported

State (*_IN_USE, *_NOT_READY)

Code	HTTP	Description
MODEL_IN_USE	409	Model being used
MODEL_NOT_READY	409	Model not ready for operation
TRAINING_IN_PROGRESS	409	Training already running
INSUFFICIENT_DATA	400	Not enough training data

System (INTERNAL_*, SERVICE_*)

Code	HTTP	Description
INTERNAL_ERROR	500	Unexpected server error
SERVICE_UNAVAILABLE	503	Temporary maintenance
TIMEOUT	504	Request timeout

Error Handling Best Practices

1. Check Status Code

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
elif response.status_code == 401:
    print("Authentication error - check API key")
elif response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    time.sleep(retry_after)
else:
    error = response.json()
    print(f"Error: {error['message']}")

2. Use Error Codes

try:
    response = api_call()
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    error_code = error.get('error_code')

    if error_code == 'QUOTA_EXCEEDED':
        notify_admin("Quota exceeded - upgrade needed")
    elif error_code == 'RATE_LIMIT_EXCEEDED':
        implement_backoff()
    else:
        log_error(error)

3. Extract Details

response = requests.post(url, headers=headers, json=data)

if response.status_code == 400:
    error = response.json()
    details = error.get('details', {})

    for field, message in details.items():
        print(f"Validation error in '{field}': {message}")

4. Retry Logic

def api_call_with_retry(func, max_retries=3):
    """Retry API calls with exponential backoff."""
    for attempt in range(max_retries):
        try:
            response = func()

            if response.status_code == 200:
                return response.json()

            elif response.status_code in [500, 503]:
                # Server error - retry
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                    continue
                else:
                    raise

            elif response.status_code == 429:
                # Rate limit - wait and retry
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue

            else:
                # Client error - don't retry
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

    raise Exception("Max retries exceeded")

5. Logging Errors

import logging

def log_api_error(response):
    """Log API errors with context."""
    if response.status_code >= 400:
        error = response.json()

        logging.error(
            f"API Error: {error.get('error')} "
            f"(Code: {error.get('error_code')}) - "
            f"{error.get('message')}",
            extra={
                'status_code': response.status_code,
                'error_code': error.get('error_code'),
                'details': error.get('details'),
                'url': response.url
            }
        )

Troubleshooting Guide

Problem: Authentication Fails

Symptoms:

• 401 Unauthorized errors
• "Invalid API key" message

Checklist:

1. ✅ API key included in header?
2. ✅ Using correct format: Bearer YOUR_API_KEY?
3. ✅ No typos in API key?
4. ✅ Using correct environment key (test vs live)?
5. ✅ Key not revoked in dashboard?

Problem: File Upload Fails

Symptoms:

• 400 Bad Request
• "Unsupported format" or "Invalid file"

Checklist:

1. ✅ File format supported? (MP3, WAV, FLAC, M4A, AAC, OGG)
2. ✅ File size under limit? (500MB standard, TUS for larger)
3. ✅ File not corrupted?
4. ✅ Using correct Content-Type?
5. ✅ multipart/form-data for file uploads?

Problem: Rate Limits

Symptoms:

• 429 Too Many Requests
• Frequent "Rate limit exceeded"

Solutions:

1. Implement exponential backoff
2. Use webhooks instead of polling
3. Cache responses
4. Batch operations
5. Upgrade plan

See Rate Limits.

Problem: Quota Exceeded

Symptoms:

• 402 Payment Required
• "Quota exceeded" message

Solutions:

1. Check current usage in dashboard
2. Upgrade plan
3. Wait for monthly reset
4. Delete unused documents to free storage

Problem: Training Fails

Symptoms:

• Custom model training_status = 5
• Training error message

Checklist:

1. ✅ Minimum 5 hours of training data?
2. ✅ Transcripts accurate (95%+)?
3. ✅ Audio/transcript pairs match?
4. ✅ Files not corrupted?

See Custom Models - Troubleshooting.

Getting Help

Self-Service

1. Check error message and details
2. Review relevant documentation
3. Search Community Forum
4. Check Status Page

Contact Support

Include in your support request:

• Error code and message
• Request ID (from X-Request-ID header)
• Timestamp of error
• Steps to reproduce
• Code sample (sanitize API keys!)

Email: support@scriptix.io

Related Documentation

• Authentication - API key setup
• Rate Limits - Rate limiting details
• API Overview - API introduction

---

Tip: Always check the error_code field for programmatic error handling.