Type at least two letters.

    ↑ ↓ to moveEnter to open

    Errors

    Every error is an RFC 9457 problem with a stable code. The full list, and what to do with each.

    Updated

    The shape of an error

    Errors use Content-Type: application/problem+json (RFC 9457):

    HTTP/1.1 409 Conflict
    Content-Type: application/problem+json
    
    {
      "type": "https://metricevo.com/problems/run_in_progress",
      "title": "Conflict",
      "status": 409,
      "code": "run_in_progress",
      "detail": "An audit for this site is already waiting or running.",
      "requestId": "req_01JCA40000000000000000000",
      "runId": "run_01JCA40000000000000000000"
    }
    
    Field Use it for
    code Branch on this. It is stable within v1.
    status The HTTP status, repeated.
    detail A sentence for people. It may change; do not parse it.
    requestId Quote it when you report a problem.
    siteId, runId On some conflicts: the existing object to use instead.

    Codes

    Status code Means What to do
    400 invalid_request A field is missing or wrong, or the body is not a JSON object. Fix the request from detail; do not retry unchanged.
    400 url_policy_denied The address is not a public website. See which addresses can be audited.
    400 idempotency_key_required POST /audit-runs without an Idempotency-Key. Send one, for example a UUID.
    401 unauthorized No key was sent. Send Authorization: Bearer ….
    401 invalid_api_key The key is wrong, revoked or expired, or its account is not active. Check the key; create a new one if needed.
    403 developer_mode_required Developer tools are off for the account (API-key calls, key management, automations, incoming webhooks). The account owner turns them on in Settings → Developer tools. See Developer tools.
    403 insufficient_scope The key lacks the scope this call needs. Create a key with the scope named in detail.
    403 session_required Key management with a key. Manage keys in the app.
    404 not_found No such id, or it belongs to another account, or no such endpoint. Check the id and the path.
    405 method_not_allowed The path exists, the method does not. See the reference.
    409 site_exists The site is already on your list. Use siteId from the body.
    409 run_in_progress The site already has a waiting or running audit. Poll runId from the body.
    409 idempotency_conflict The Idempotency-Key was used for another site. Use a new key for a new audit.
    403 plan_limit Your plan does not include this, for example a write with an API key or extra sites on Free. Upgrade, or choose what the plan includes.
    403 session_required Billing changes need a signed-in session, not an API key. Do it in the app under Plan & billing.
    409 already_subscribed A checkout for an account that already has a plan. Change the plan in the billing portal.
    409 no_billing_account The billing portal before any checkout. Choose a plan first.
    429 quota_exceeded An account limit: sites, audits, automations, keys or reports. See Limits; wait Retry-After if present.
    409 sites_in_use Fewer extra sites than the sites you already use. Remove sites first.
    429 credit_limit_reached The audit needs more credits than your plan has left this month. Choose a smaller scope, wait for the next month, or upgrade.
    429 spend_cap_reached The audit would go over your monthly spend cap. Raise the cap, or wait for the next period.
    429 rate_limited More requests a minute than your plan allows (Free 30, paid 120). Wait Retry-After seconds (60).
    503 billing_unavailable Payments are not open yet, or the payment service did not answer. Try again later.
    503 unavailable A temporary problem on our side. Retry with backoff: 1 s, 2 s, 4 s…

    Retry or not

    • Retry 429 after Retry-After, and 503 with backoff.
    • Retry a network error or a timeout of POST /audit-runs with the same Idempotency-Key: you get the same run, never a second audit.
    • Do not retry any other 4xx unchanged. It will fail the same way.

    Errors of a run

    An audit that started but could not finish is not an HTTP error: the run ends with status: failed and an errorCode. See Asynchronous audits.