Errors · Fylane

Every error Fylane can return — 36 codes across 12 HTTP statuses — with whether retrying helps.

Every error carries the same shape and answers the same four questions: what happened, whether retrying helps, what to change, and where to read more. Switch on code, never on message — messages are written for humans and are allowed to improve.

The envelope

{
  "type": "https://fylane.dev/errors/unsupported-file",
  "code": "unsupported_file",
  "message": "This file format is not supported.",
  "retryable": false,
  "request_id": "req_01JBQ8Z5T7WXK9MNP2RSTVA3C4",
  "docs_url": "https://fylane.dev/docs/errors/unsupported-file"
}

A 404 never confirms that something exists

A resource belonging to another organisation returns 404, not 403. A 403 would tell an attacker the id is real, which is exactly the thing worth hiding.

HTTP 400

Code	Retryable	Meaning
`invalid_request`	No	The request is malformed or missing required fields.
`unsupported_file`	No	This file format is not supported.
`file_too_large`	No	The file exceeds the maximum size for your plan.
`corrupted_file`	No	The file could not be parsed and appears to be corrupted.
`encrypted_file`	No	The file is password-protected and cannot be processed.
`unsupported_operation`	No	This operation is not available for this file type.

HTTP 401

Code	Retryable	Meaning
`missing_credentials`	No	No API key was provided.
`invalid_api_key`	No	The API key is not valid.
`expired_api_key`	No	This API key has expired.
`revoked_api_key`	No	This API key has been revoked.
`api_key_in_query`	No	API keys must be sent in the Authorization header, never in the URL.

HTTP 402

Code	Retryable	Meaning
`payment_required`	No	Payment for this organization has failed; processing is paused until it succeeds.

HTTP 403

Code	Retryable	Meaning
`insufficient_scope`	No	This API key does not have the required scope.
`ip_not_allowed`	No	This API key is restricted to a set of IP addresses that does not include this one.
`environment_mismatch`	No	A test key cannot access live resources, and vice versa.
`organization_suspended`	No	This organization has been suspended.
`forbidden`	No	You do not have permission to perform this action.
`key_restricted`	No	This API key is not allowed to run this operation.

HTTP 404

Code	Retryable	Meaning
`not_found`	No	No such resource.

HTTP 409

Code	Retryable	Meaning
`idempotency_conflict`	No	This Idempotency-Key was already used with a different request body.
`upload_session_consumed`	No	This upload session has already been used.
`conflict`	No	The resource is in a state that does not allow this operation.

HTTP 413

Code	Retryable	Meaning
`payload_too_large`	No	The request body is too large.

HTTP 422

Code	Retryable	Meaning
`malware_detected`	No	The file was rejected because it failed a security scan.
`policy_violation`	No	The file violates the acceptable use policy.
`validation_failed`	No	The file does not meet the validation policy supplied with the upload.
`output_validation_failed`	No	Processing produced output that failed verification, so it was discarded.
`unsupported_input`	No	This file is not something the requested operation can process.

HTTP 429

Code	Retryable	Meaning
`key_spend_limit`	No	This API key has reached its credit spend cap for the current window.
`rate_limited`	Yes	Too many requests. Retry after the interval in the Retry-After header.
`concurrency_limit`	Yes	Too many jobs are running concurrently for this organization.
`credits_exhausted`	No	This organization has no processing credits remaining.

HTTP 500

Code	Retryable	Meaning
`internal_error`	Yes	An unexpected error occurred on our side.

HTTP 503

Code	Retryable	Meaning
`processing_unavailable`	Yes	Processing capacity is temporarily unavailable.
`dependency_unavailable`	Yes	A required service is temporarily unavailable.

HTTP 504

Code	Retryable	Meaning
`timeout`	Yes	The operation took too long and was stopped.