Best Practices

Common Issues

Issue: "Failed to download document"

Cause: URL not accessible

Solution:

• Use S3 presigned URLs
• Verify URL returns FTR file
• Check URL hasn't expired

Issue: "Invalid FTR file format"

Cause: Corrupted or invalid file

Solution:

• Test file in FTR player first
• Verify file extension is .ftr
• Check file size is not 0 bytes

Issue: Slow conversion

Cause: Large file or multi-channel audio

Solution:

• Use webhooks instead of polling
• 8-hour files can take 10-15 minutes
• Set timeout to 2x file duration

Issue: Permission denied (403)

Cause: API key missing converter access

Solution:

• Verify ftr_converter in API key permissions
• Contact support to enable access

Best Practices

Before Converting

1. Verify FTR file quality - test in FTR player
2. Use S3 presigned URLs - more secure than public URLs
3. Plan storage - download M4A within 7 days

During Conversion

1. Use webhooks for long files (1+ hours)
2. Implement retry logic - exponential backoff
3. Monitor progress - check progress field

After Completion

1. Download immediately - files expire after 7 days
2. Verify audio - play M4A to confirm quality
3. Archive properly - store in your own S3/storage
4. Clean up - delete conversion jobs when done

Pricing

Quick Reference

# Convert FTR to M4A
curl -X POST https://api.case.dev/convert/v1/process \
  -H "Authorization: Bearer sk_case_..." \
  -d '{"input_url":"https://s3.../file.ftr"}'

# Check status
curl https://api.case.dev/convert/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_case_..."

# Download
curl https://api.case.dev/convert/v1/download/JOB_ID \
  -H "Authorization: Bearer sk_case_..." \
  -o output.m4a

# Delete
curl -X DELETE https://api.case.dev/convert/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_case_..."