Error Handling

All errors return a consistent JSON structure with a machine-readable code and a human-readable error message.

Error Response Format

Error response structure

{
  "error": "Failed to parse input file: unexpected tag at line 12",
  "code": "PARSE_ERROR"
}

Field	Type	Description
`error`	string	Human-readable error message
`code`	string	Machine-readable error code for programmatic handling

Error Codes

HTTP Status	Code	Description
`400`	`MISSING_FILE`	No file was included in the request body
`400`	`MISSING_PARAM`	A required parameter is missing (e.g. `to`)
`400`	`UNKNOWN_FORMAT`	Could not auto-detect the file format
`400`	`UNSUPPORTED_FORMAT`	The specified format is not recognized or supported
`400`	`PARSE_ERROR`	Failed to parse the input file (malformed or corrupted data)
`400`	`VALIDATION_ERROR`	A request parameter failed validation (includes field name and reason)
`401`	`UNAUTHORIZED`	Missing or invalid API key
`413`	`FILE_TOO_LARGE`	File exceeds the 10MB size limit
`429`	`RATE_LIMITED`	Rate limit exceeded — check `Retry-After` header
`429`	`QUOTA_EXCEEDED`	Monthly conversion quota exhausted
`500`	`INTERNAL_ERROR`	Unexpected server error — contact support if persistent

Best Practices

Check the HTTP status code first. A 2xx status means success. Any 4xx or 5xx status means an error occurred.
Parse the error JSON. The response body always contains an error message and a code string.
Use the code field for programmatic handling. The error message may change, but the code string is stable and safe to match against.
Handle 429 with exponential backoff. Always respect the Retry-After header. See Rate Limits for details.
Log the full error response. Include the HTTP status, code, and error message in your logs for debugging.

Error handling example

try {
  const response = await fetch('https://api.finconvert.dev/v1/convert', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer fc_live_xxxxx' },
    body: form,
  })

  if (!response.ok) {
    const { error, code } = await response.json()

    switch (code) {
      case 'RATE_LIMITED':
        const retryAfter = response.headers.get('Retry-After')
        // Wait and retry
        break
      case 'QUOTA_EXCEEDED':
        // Upgrade plan or wait for reset
        break
      case 'UNAUTHORIZED':
        // Check API key
        break
      default:
        console.error(`API error [${code}]: ${error}`)
    }
    return
  }

  // Process successful response
  const blob = await response.blob()
} catch (err) {
  // Network error
  console.error('Request failed:', err)
}

Ready to get started?

Get your API key from the dashboard and start converting bank statements.

Go to Dashboard