Skip to main content

​
Overview

The Aifano API uses standard HTTP status codes to indicate the success or failure of a request. All error responses include a JSON body with an error field describing the issue.

​
Error Response Format

{
  "error": "A human-readable description of what went wrong."
}
Some errors include additional fields: 
{
  "error": "Credit limit reached. You have used 1000 of 1000 credits this month.",
  "code": "CREDIT_LIMIT_EXCEEDED",
  "credits_used": 1000,
  "credit_limit": 1000
}

​
HTTP Status Codes

​
Success

CodeDescription
200 OKRequest succeeded. Response body contains the result.
201 CreatedResource created successfully (e.g., document added to pipeline).

​
Client Errors

CodeDescriptionCommon Causes
400 Bad RequestThe request body is invalid or missing required fields.Missing input field, invalid JSON, unsupported file type.
401 UnauthorizedAuthentication failed.Missing Authorization header, invalid API key, expired key, revoked key.
403 ForbiddenYou don’t have permission for this action.Insufficient API key scopes, registration disabled.
404 Not FoundThe requested resource doesn’t exist.Invalid job ID, pipeline not found, document not found.
409 ConflictResource already exists.Duplicate pipeline name, document already in pipeline.
422 Unprocessable EntityThe request is well-formed but contains invalid parameters.Invalid schema, malformed extraction config.
429 Too Many RequestsCredit limit exceeded or rate limit hit.Monthly credit limit reached.

​
Server Errors

CodeDescriptionWhat to Do
500 Internal Server ErrorSomething went wrong on our end.Retry the request. If it persists, contact support.
502 Bad GatewayUpstream processing service is unavailable.Wait a moment and retry.
503 Service UnavailableThe service is temporarily overloaded.Retry with exponential backoff.
504 Gateway TimeoutThe request took too long to process.Use the async endpoint instead.

​
Common Errors

​
Authentication Errors

// Missing Authorization header
{ "error": "Missing or invalid Authorization header. Use: Bearer <api_key>" }

// Invalid API key format
{ "error": "Invalid API key format" }

// Invalid or unknown API key
{ "error": "Invalid API key" }

// Revoked API key
{ "error": "API key has been revoked" }

// Expired API key
{ "error": "API key has expired" }

​
Input Errors

// Missing input
{ "error": "No input provided. Use 'aifano://file_id' or a public URL." }

// Unsupported file type
{ "error": "Unsupported file type. Supported: PDF, PNG, JPG, JPEG, TIFF, DOCX, PPTX." }

​
Credit Errors

{
  "error": "Credit limit reached. You have used 1000 of 1000 credits this month. Please upgrade your plan or wait until next month.",
  "code": "CREDIT_LIMIT_EXCEEDED",
  "credits_used": 1000,
  "credit_limit": 1000
}

​
Processing Errors

// Parse failure
{ "error": "Parse failed" }

// Extract failure
{ "error": "Extract failed" }

// Split failure
{ "error": "Split failed" }

// Edit failure
{ "error": "Edit failed" }

// Cancel failure
{ "error": "Cancel failed" }

​
Error Handling Best Practices

Don’t assume a 200 response. Check the status code before processing the response body.
Server errors are usually transient. Retry with exponential backoff (e.g., 1s, 2s, 4s, 8s) up to a maximum number of attempts.
If you’re getting 504 Gateway Timeout errors, switch to the async variant of the endpoint to avoid timeouts.
Track the usage field in API responses to anticipate when you’re approaching your credit limit. Upgrade your plan before hitting the limit.
Check that your file URL is accessible, the file type is supported, and required fields are present before making API calls.