API errors, rate limits, and fingerprints

Error responses

DeployMonitor returns JSON errors for the project API. Use the HTTP status and response body together when deciding whether to correct or retry a request.

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 or changing maintenance.

404 Not Found means the requested project, log, or maintenance record could not be found in the token's project scope. Missing resources and resources belonging to another project use a generic response:

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

409 Conflict means a maintenance request is valid but conflicts with the current maintenance lifecycle. For example, DeployMonitor returns 409 when:

• The project already has scheduled or active maintenance.

• Completed or cancelled maintenance is updated.

• The start time of active maintenance is changed.

• A scheduled window is ended instead of cancelled.

• Active maintenance is cancelled instead of ended.

Correct the lifecycle action or retrieve the current maintenance state before retrying.

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 reads, project-log reads, and all project-maintenance endpoints allow 60 requests per minute per authenticated user. Tokens owned by the same user share that limit.

Project-log creation has separate limits:

• 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, 409, or 422 response without correcting the request or resolving the conflicting state.

Use fingerprints for idempotent project logs

A project-log 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, 429 responses, and temporary server errors with exponential backoff. If a project-log request may have succeeded, retry with the same fingerprint and treat a duplicate-fingerprint 422 as confirmation that the event already exists.

For maintenance conflicts, retrieve GET /api/v1/projects/{project}/maintenance or the specific maintenance record before choosing the next action.