Skip to Content
API ReferenceErrors

Errors

The IdentityCall API uses standard HTTP status codes to indicate the success or failure of requests. This page documents all error responses and how to handle them.

HTTP Status Codes

CodeNameDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentRequest succeeded (no response body)
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenValid API key but insufficient permissions
404Not FoundResource doesn’t exist
422Unprocessable EntityInvalid input data
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

Error Response Format

All errors return a JSON object with an error field:

{
  "error": "Description of what went wrong"
}

For validation errors (422), you may receive an array of error messages:

{
  "errors": ["Field 1 is invalid", "Field 2 is required"]
}

Common Errors

Authentication Errors (401)

{
  "error": "Invalid or expired API key"
}

Causes:

  • API key is missing from the request
  • API key format is incorrect (should start with idc_)
  • API key has been revoked
  • API key has expired

Solution:

  1. Verify your API key is correct
  2. Check the Authorization header format: Bearer idc_your_key
  3. Generate a new API key if needed

Permission Errors (403)

{
  "error": "Read permission required"
}
{
  "error": "Write permission required"
}
{
  "error": "Delete permission required"
}

Cause: Your API key doesn’t have the required permission for this action.

Solution: Create a new API key with the appropriate permissions or update your existing key’s permissions.

Not Found Errors (404)

{
  "error": "Resource not found"
}

Causes:

  • Recording ID doesn’t exist
  • Recording belongs to a different account
  • Recording was deleted

Solution: Verify the resource ID and that it belongs to your account.

Validation Errors (422)

{
  "error": "file is required"
}
{
  "error": "Transcription not available"
}

Causes:

  • Missing required fields
  • Invalid field values
  • Resource in wrong state (e.g., transcription not yet complete)

Solution: Check the request body and ensure all required fields are present and valid.

Rate Limit Errors (429)

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Cause: Too many requests in a short time period.

Solution: Wait for the time specified in retry_after (seconds) before retrying.

Error Handling Best Practices

Retry with Exponential Backoff

For transient errors (429, 500), implement retry logic:

import requests
import time
 
def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
 
        if response.status_code == 200:
            return response.json()
 
        if response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = response.json().get('retry_after', 60)
            time.sleep(retry_after)
            continue
 
        if response.status_code >= 500:
            # Server error - exponential backoff
            time.sleep(2 ** attempt)
            continue
 
        # Client error - don't retry
        response.raise_for_status()
 
    raise Exception("Max retries exceeded")

Handle Specific Error Types

import requests
 
def handle_api_response(response):
    if response.status_code == 200:
        return response.json()
 
    error_data = response.json()
    error_message = error_data.get('error', 'Unknown error')
 
    if response.status_code == 401:
        raise AuthenticationError(error_message)
    elif response.status_code == 403:
        raise PermissionError(error_message)
    elif response.status_code == 404:
        raise NotFoundError(error_message)
    elif response.status_code == 422:
        raise ValidationError(error_message)
    elif response.status_code == 429:
        raise RateLimitError(error_message, error_data.get('retry_after'))
    else:
        raise APIError(error_message)

Log Errors for Debugging

Include request IDs and timestamps in your error logs:

import logging
from datetime import datetime
 
def log_api_error(response, request_id=None):
    logging.error(
        "API Error",
        extra={
            "timestamp": datetime.utcnow().isoformat(),
            "status_code": response.status_code,
            "error": response.json().get("error"),
            "request_id": request_id,
            "url": response.url
        }
    )

Getting Help

If you encounter persistent errors:

  1. Check the API status page 
  2. Review the API changelog for breaking changes
  3. Contact support at support@identitycall.com with:
    • Error message
    • Request details (endpoint, parameters)
    • Timestamp
    • Your account email
Get SummaryUploading Recordings