Skip to main content

​
Overview

The Ambient AI Scribe API uses standard HTTP status codes to indicate success or failure. All error responses include a JSON body with error details to help you understand and resolve issues.

​
HTTP Status Codes

The API uses the following HTTP status codes:

​
Success Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded with no response body

​
Client Error Codes

  • 400 Bad Request - Invalid request parameters or body
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., duplicate creation)
  • 422 Unprocessable Entity - Validation error
  • 429 Too Many Requests - Rate limit exceeded

​
Server Error Codes

  • 500 Internal Server Error - Unexpected server error
  • 502 Bad Gateway - Gateway error
  • 503 Service Unavailable - Service temporarily unavailable
  • 504 Gateway Timeout - Request timeout

​
Error Response Format

Error responses follow a consistent format: 
{
  "detail": "Additional context or validation errors"
}

​
Common Error Scenarios

​
Authentication Errors

{
  "detail": "Could not validate credentials"
}

​
Validation Errors

{
  "detail": "You do not have access to these template_ids [234234]"
}

​
Not Found

404 Not Found
{
  "detail": "Transcription not found"
}

​
Rate Limiting

429 Too Many Requests
{
  "details": "Too many requests"
}

​
Error Handling Best Practices

​
1. Check Status Codes

Always check the HTTP status code before processing the response:
  • JavaScript
  • Python
const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error.message);
}

const data = await response.json();

​
2. Handle Specific Error Codes

Implement specific handling for different error types: 
try {
  const response = await fetch(url, options);
  const data = await response.json();
  
  if (!response.ok) {
    switch (response.status) {
      case 401:
        // Token expired, re-authenticate
        await reauthenticate();
        break;
      case 429:
        // Rate limited, wait and retry
        await waitForRateLimit(data.error.details.reset_at);
        break;
      case 404:
        // Resource not found
        console.error('Resource not found:', data.error.details);
        break;
      default:
        console.error('API error:', data.error.message);
    }
    throw new Error(data.error.message);
  }
  
  return data;
} catch (error) {
  // Handle network errors or other exceptions
  console.error('Request failed:', error);
  throw error;
}

​
3. Implement Retry Logic

For transient errors (5xx status codes), implement retry logic with exponential backoff: 
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry client errors (4xx)
      if (response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Retry server errors (5xx)
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw new Error(`Server error: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

​
4. Log Errors Appropriately

Log errors with sufficient context for debugging: 
function handleApiError(error, context) {
  const logData = {
    timestamp: new Date().toISOString(),
    error: error.error || error.message,
    context: context,
    statusCode: error.statusCode
  };
  
  // Log to your error tracking service
  console.error('API Error:', JSON.stringify(logData, null, 2));
}

​
5. Handle Rate Limits

When receiving a 429 response, wait until the rate limit resets: 
async function handleRateLimit(error) {
  const resetAt = new Date(error.details.reset_at);
  const waitTime = resetAt - new Date();
  
  if (waitTime > 0) {
    console.log(`Rate limited. Waiting ${waitTime}ms until reset...`);
    await new Promise(resolve => setTimeout(resolve, waitTime));
  }
}

​
Testing Error Handling

Test your error handling by:
  1. Invalid credentials - Test with wrong username/password
  2. Expired tokens - Test with expired or invalid tokens
  3. Invalid parameters - Test with missing or invalid request data
  4. Rate limiting - Test by making rapid requests
  5. Network errors - Test with network interruptions

​
Getting Help

If you encounter errors that aren’t covered in this guide:
  1. Check the error message and details in the response
  2. Verify your request format matches the API specification
  3. Review the authentication guide
  4. Contact support with:
    • Error code and message
    • Request details (endpoint, parameters, headers)
    • Response body
    • Timestamp of the error