Errors

Every error response of the V2 HTTP API, has this envelope:

{
  "error": {
    "code": "not_found",
    "message": "The campaign 0190a4e2-0000-7000-8000-000000000001 does not exist.",
    "details": {
      "resource": "campaign",
      "id": "0190a4e2-0000-7000-8000-000000000001"
    }
  }
}

• code is a stable snake_case value. Use it in your code.
• message is text for a person. It can change.
• details holds extra data, or null.

Request ID

Every V2 response has an X-Request-ID header. When you send an X-Request-ID of 1 to 128 characters (letters, digits, ., _ and -), the response uses your value. Otherwise Signal makes a new ID. Log the ID, and send it to support with a question about a request.

Status codes

Other 4xx statuses use the same envelope. Their code names the status, for example method_not_allowed for 405.

Permission errors

Product operations check explicit Permissions. The organization role does not replace those checks. API keys use their assigned permissions within the owner's current access.

{
  "error": {
    "code": "access_denied",
    "message": "The operation requires monitor.write.",
    "details": {
      "resource": "monitor",
      "action": "write",
      "operation_id": "update_monitor"
    }
  }
}

Handle code, resource, action and operation_id as structured values. The message text can change. Ask an Owner or Admin to review the owner's access and the key's assigned limit. Repeating the request does not repair a missing permission. A denied operation changes no product data, starts no work and spends no credits.

When only embedded data is restricted, a permitted read can return a partial representation with a restricted list. An explicitly requested resource without its required read permission gives 403. Read Restricted response data.

Validation errors

A request that does not match the schema gives 422 with the code validation_error. An ID that is not a UUID also gives this code. details.errors lists each problem:

{
  "error": {
    "code": "validation_error",
    "message": "The request is not valid: body.name: Field required",
    "details": {
      "errors": [
        { "loc": ["body", "name"], "message": "Field required", "type": "missing" }
      ]
    }
  }
}

Some operations give a 422 response with a specific code:

| idempotency_key_reused | create_campaign, create_monitor, run_monitor, start_discovery, start_import, upload_import | The same key names another request body. |

Validation detail types

validation_error is the envelope code. error.details.errors[].type identifies an individual invalid field; it is not a second envelope code.

Schema validation also reports constraint types such as string_too_short, string_too_long, string_pattern_mismatch, greater_than_equal, less_than_equal, too_short, too_long, uuid_parsing, enum, literal_error, union_tag_invalid and union_tag_not_found. Their operations and limits come from the affected request schema. Inspect each loc to identify the field. See the operation schema for accepted values.

Conflict and retry

Every 409 includes details.retryable. Use the code to choose the next action:

A discovery schedule that disappears during an update returns 404 not_found. A schedule validation failure returns 422 validation_error. These failures can follow earlier changes to campaign settings. Re-read the campaign before correcting and retrying; the update is not an atomic rollback.

Use bounded retries with increasing delays. See Retry safely.

422 idempotency_key_reused means the key belongs to another request body. Use a fresh key for a new request.