Error meanings

Every refusal carries a stable code. The body keeps detail as a plain message and adds an error object you can branch on:

{
  "detail": "Every pixel has the same value ...",
  "error": {
    "code": "INPUT_BLANK",
    "message": "Every pixel has the same value ...",
    "fix": "Check the exposure and that the laser was on; ...",
    "docs": "/docs/errors#INPUT_BLANK"
  }
}

A 500 also carries a run_id; send it to us and we can find the failure in the log. 429 responses carry a Retry-After header (seconds). Request parameter errors (PARAM_OUT_OF_RANGE) keep the usual list of field errors in detail.

Bad uploads and bad parameters are checked before a request waits for a reconstruction slot, so they come back in well under a second.

INPUT_FORMAT_UNSUPPORTED

HTTP 400. The file extension is not one the service reads.

What to do: Upload a .tif/.tiff, .png, .jpg/.jpeg, .npy, .npz, .h5 or .hdf5 file.

INPUT_EMPTY

HTTP 422. The uploaded file has zero bytes.

What to do: Check the upload actually attached the file (curl needs -F "file=@path", with the @).

INPUT_UNREADABLE

HTTP 422. The file could not be decoded: truncated, corrupt, or not the format its extension claims.

What to do: Re-export the frame from the camera software and upload it again without converting it.

INPUT_BLANK

HTTP 422. Every pixel has the same value (all dark or fully saturated), so there is no hologram to reconstruct.

What to do: Check the exposure and that the laser was on; a usable frame has visible fringes.

INPUT_CHANNELS_UNSUPPORTED

HTTP 422. The image has a channel layout the service does not read (more than three axes, or a channel count other than 1, 3 or 4).

What to do: Upload a single 2-D frame: monochrome, or an RGB/RGBA image from a colour sensor.

INPUT_FILE_TOO_LARGE

HTTP 413. The upload is larger than the byte limit for this service or your plan.

What to do: Crop the frame to the region of interest (do not downscale) and upload it again.

INPUT_DIMENSIONS_TOO_LARGE

HTTP 413. The image is wider or taller than the per-axis pixel limit.

What to do: Crop the frame to the region of interest; never downscale, because that changes the effective pixel pitch.

INPUT_RAW_DECODER_UNAVAILABLE

HTTP 415. A camera RAW file was uploaded but this server has no RAW decoder installed.

What to do: Convert to 16-bit PNG or TIFF (green channel, no demosaic) and upload that.

PARAM_OUT_OF_RANGE

HTTP 422. A parameter is missing, has the wrong type, or is outside its allowed range.

What to do: Check the parameter named in the message against the interactive reference at /docs/api.

PARAM_PITCH_NOT_ABOVE_WAVELENGTH

HTTP 422. pixel_pitch_um must be strictly greater than wavelength_um (a sampling requirement).

What to do: Check the two values are not swapped and that wavelength is in micrometres: 0.635, not 635.

PARAM_MODE_INVALID

HTTP 400. An unrecognised mode value (holography_mode, quality_mode, processing_profile, inline_method or geometry) was rejected rather than silently downgraded.

What to do: Use one of the values listed in the message; spelling variants such as off_axis are accepted.

CALIBRATION_PROFILE_NOT_FOUND

HTTP 404. The calibration_profile_id does not belong to this account.

What to do: List your profiles, or run a calibration first and pass the profile id it returns.

AUTH_INVALID_KEY

HTTP 401. The API key or token is missing, unknown, or expired.

What to do: Send the key as 'Authorization: Bearer '; rotate it from your account page if it was lost.

ACCOUNT_INACTIVE

HTTP 403. The account exists but is deactivated.

What to do: Contact system@apertureapi.com to reactivate the account.

TRIAL_ENDED

HTTP 402. The account's free 3-month trial has ended.

What to do: Pick a plan or pay-as-you-go on the signup page; your API key stays the same.

RATE_LIMIT_PER_MINUTE

HTTP 429. Too many requests in the current one-minute window for your plan.

What to do: Wait the number of seconds in the Retry-After header, then retry.

QUOTA_MONTHLY_EXCEEDED

HTTP 429. The plan's monthly reconstruction quota is used up.

What to do: Wait for the month to roll over (Retry-After gives the seconds) or move to a larger plan.

PUBLIC_RATE_LIMIT

HTTP 429. The no-account form's per-IP hourly limit was reached.

What to do: Wait the number of seconds in the Retry-After header, or sign up for an API key.

CAPACITY_INSUFFICIENT_MEMORY

HTTP 507. The requested field needs more memory than the server has free right now.

What to do: Use processing_profile=standard, crop the frame, or retry in a minute.

INTERNAL_RECONSTRUCTION_FAILED

HTTP 500. The service failed while processing a valid request. This is our fault, not your input.

What to do: Retry once; if it fails again, send the run_id from this response to system@apertureapi.com.

DATA_UNDER_LEGAL_HOLD

HTTP 409. The data cannot be deleted because a retention hold applies to it.

What to do: Contact system@apertureapi.com with the archive id; held records are released when the hold ends.

The service refuses ambiguous or out-of-range requests explicitly instead of returning a quietly degraded result.