Skip to content

Reference

Errors

Status codes, stable error codes and retries.

Every error response has the same JSON body:

{
"code": "JOB_NOT_FOUND",
"message": "Job not found or access denied.",
"request_id": "req_8f2c1a"
}
Field Meaning
code Stable, machine-readable error code. Branch on this, never on message.
message Human-readable description, safe to show to your users.
request_id Identifier of the request. Quote it when you contact support.
Status When
400 The request is malformed, a required field is missing or the file cannot be read.
401 The API key is missing or invalid.
403 The key has no access to this resource.
404 The job or resource does not exist.
409 The resource is in the wrong state, or you do not have enough credits.
410 The result has expired.
413 The upload is too large.
422 A value is invalid.
429 Too many requests. Retry with backoff.
5xx Something failed on our side. Retry with backoff.

Retry 408, 429 and 5xx responses with exponential backoff. Do not retry other 4xx responses unchanged: they fail the same way again.

A failed request raises a typed error that carries the code, message and request_id. The SDKs retry 408, 429 and 5xx responses twice and time out after 60 seconds; both can be changed.

from byteit.core.api_error import ApiError
from byteit.errors import NotFoundError
try:
client.jobs.get(id="3f9a1c2e-5b7d-4e8f-9a0b-1c2d3e4f5a6b")
except NotFoundError:
...
except ApiError as error:
print(error.status_code, error.body)

Codes are only added in minor versions. A code is renamed or removed only in a new major version, so you can branch on them safely.

Authentication

  • UNAUTHORIZED401Authentication is required to perform this action.
  • FORBIDDEN403You do not have permission to perform this action.

Request

  • MISSING_REQUIRED_FIELD400A required field is missing.
  • INVALID_VALUE422The provided value is invalid.

Files

  • PDF_PASSWORD_PROTECTED400The uploaded file is password protected and could not be processed. Please remove the password and try again.
  • PDF_NOT_VALID400The uploaded file is not a valid PDF and could not be processed. The file appears to be corrupted or truncated; please check the file and try again.
  • PDF_TRUNCATED400The uploaded file is truncated and could not be processed. The file appears to be corrupted; please upload the complete file and try again.
  • PDF_CORRUPTED400The uploaded file is corrupted and could not be processed. The file appears to be damaged or truncated; please check the file and try again.
  • IMAGE_CORRUPTED400The uploaded image is corrupted and could not be processed. The image appears to be damaged or truncated; please check the file and try again.
  • UNSUPPORTED_FILE_TYPE400Unsupported file type.
  • FILE_TOO_LARGE413The upload exceeds the maximum request size.
  • UNSUPPORTED_OFFICE_TYPE400Unsupported Office file type.
  • UNSUPPORTED_SPREADSHEET400Spreadsheet files (.xlsx, .xls) are not supported for CV extraction.
  • NO_TEXT_EXTRACTED400No text could be extracted from the uploaded {file_type} document.
  • RTF_NOT_VALID400The uploaded file is not a valid RTF document.
  • ARCHIVE_INVALID400The uploaded file is not a valid archive.
  • ARCHIVE_EMPTY400The uploaded document appears to be an empty or invalid archive.

Jobs

  • JOB_NOT_FOUND404Job not found or access denied.
  • RESULT_EXPIRED410The requested result has expired and is no longer available.

Extraction

  • EXTRACT_JOB_NOT_FOUND404Extract job not found.

State

  • STATE_CONFLICT409The operation conflicts with the current state.
  • JOB_ALREADY_FINALIZED409This job has already been processed.

Credits

  • REFUND_DESTINATION_MISSING400We couldn't refund the credits automatically; we'll reconcile this.
  • INSUFFICIENT_CREDITS409You do not have enough credits for this operation.

Processing

  • EMPTY_MODEL_RESPONSE500The document could not be processed because no data was returned.
  • MALFORMED_MODEL_RESPONSE500The document could not be processed due to an invalid response.
  • MODEL_PROCESSING_ERROR500The document could not be processed. Please try again.
  • UPSTREAM_ERROR502A dependency failed to process the request. Please try again later.

General

  • INTERNAL_SERVER_ERROR500An unexpected error occurred. Please try again later.
  • SERVICE_UNAVAILABLE503The service is temporarily unavailable. Please try again later.
  • RESOURCE_NOT_FOUND404The requested resource was not found.