Provenance

Errors

When a request fails, the API returns an HTTP status code in the 4xx or 5xx range and a JSON body that names the error. This page lists every error type.

A check that cannot run is not an error. The request returns HTTP 200, and that check has the result unavailable with a reason field. Read the detectors page.

Status codes

  • Name
    2xx
    Description
    The request succeeded.
  • Name
    4xx
    Description

    The request has a problem. Read the error message, fix the request, and send it again.

  • Name
    5xx
    Description

    Something failed on our side. Wait a moment and send the request again. If the problem continues, contact us.

Error format

Every error has the same shape. The type field is stable, so you can match on it in code. The message field is written for people and can change.

  • Name
    error.type
    Type
    string
    Description

    One of the error types listed below.

  • Name
    error.message
    Type
    string
    Description

    What went wrong and, when possible, what to do about it.

  • Name
    error.documentation_url
    Type
    string
    Description

    A link to the section on this page for the error type.

Error response

{
  "error": {
    "type": "quota_exceeded",
    "message": "You have used all 500 API calls for this month. The quota resets on 2026-10-01 (UTC). Upgrade your plan for a higher limit.",
    "documentation_url": "https://provenance.pixellab.nz/errors#quota-exceeded"
  }
}

Error types

invalid_request

HTTP 400. The request body or a field in it is wrong. Common causes are a body that is not JSON, more than one media source, or a check name that does not exist. The message names the field.

authentication_error

HTTP 401. The Authorization header is missing, the key is not in the expected format, or the key is revoked. Read the authentication page.

payload_too_large

HTTP 413. The file is larger than the limit. Inline media and multipart uploads are limited to 4 MB. Files sent by url or by direct upload are limited to 25 MB. Read the detect endpoint reference for the upload flow.

media_error

HTTP 422. The API could not download the file from url. The host did not resolve, the download timed out, or the server returned an error status.

rate_limited

HTTP 429. You sent more requests in one minute than the burst limit allows. Read the Retry-After header, wait that many seconds, and send the request again. Read the rate limits page.

quota_exceeded

HTTP 429. You used every API call in your monthly quota. The quota resets on the first day of the next calendar month, in UTC. The X-Quota-Reset header gives the exact time. Upgrade your plan for a higher limit. Read the pricing page.

not_found

HTTP 404. The upload path does not exist for your account. Uploads expire two hours after they are created, and each upload can be used once.

api_error

HTTP 500 or 503. Something failed on our side. Send the request again. If the problem continues, contact us and include the X-Request-Id header from the response.

Was this page helpful?