API errors, rate limits, and fingerprints

Error responses

DeployMonitor returns JSON errors for the project API.

401 Unauthorized means the Bearer token is missing or invalid. Confirm that the complete token is present in the Authorization header.

403 Forbidden means the token is valid but cannot perform the requested operation. Common causes include:

• The token belongs to a different project.

• The token lacks the required ability.

• The token owner no longer has project access.

• The token owner no longer has a Developer or Admin role when creating logs.

An unauthorized create request can return:

{
  "message": "This token is not authorized to create logs for the requested project."
}

404 Not Found means the project or log could not be found in the requested scope. Missing resources and logs belonging to another project use a generic response:

{
  "message": "The requested resource was not found."
}

422 Unprocessable Content means one or more request fields failed validation:

{
  "message": "The change type field is required.",
  "errors": {
    "change_type": [
      "The change type field is required."
    ]
  }
}

429 Too Many Requests means a rate limit was reached. Wait before retrying and use the response's rate-limit information when available.

Rate limits

Project and log read endpoints allow 60 requests per minute per authenticated user. Tokens owned by the same user share that read limit.

Project-log creation allows:

• 120 requests per minute for each token and project.

• 2,000 requests per day for each token and project.

Use queues, batching, and backoff instead of sending bursts. Do not repeatedly retry a 401, 403, or 422 response without correcting the request.

Use fingerprints for idempotency

A fingerprint is optional, but recommended for automated events. It must be unique within one project. Reusing it in the same project returns 422 and does not create another log.

Build a stable fingerprint from immutable event data, for example:

deploy:production:abc123
plugin:woocommerce:8.0:8.1

The same fingerprint can be used in another project. This makes it suitable for the same release or component update across separate environments.

Retry safely

Retry connection failures and 429 or temporary server errors with exponential backoff. If the first request may have succeeded, retry with the same fingerprint and treat a duplicate-fingerprint 422 as confirmation that the event already exists.