Resource Conflict

At a glance

What it means

The request conflicts with the current state of the resource — either a uniqueness violation, an illegal state transition, or a concurrent edit.

When it is returned

• Data conflict / concurrent edit (agent.action: REFRESH_STATE): A unique constraint would be violated (duplicate key, name, etc.), or a concurrent edit modified the resource since you last read it. Re-reading the resource and reconciling the conflict will resolve it.
• Illegal state transition (agent.action: FIX_INPUT): The resource is in a state that disallows the requested action (e.g. attempting to undo completion on a task that was never completed, completing a work order while it is under review). Re-fetching state will not resolve the conflict — the input itself must change.

Troubleshooting

• Data conflict: Re-read the resource to inspect its current state. Reconcile the conflict (rename, change status, merge edits) and retry.
• Illegal state transition: Inspect the resource's current status and compare against the documented allowed transitions. The detail field describes the specific rule that was violated.
• For optimistic-concurrency endpoints, refresh the version/etag before resubmitting.

Example response

HTTP/1.1 409 Resource Conflict
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/resource-conflict",
  "title": "Resource Conflict",
  "status": 409,
  "detail": "A webhook with this URL is already registered for the company.",
  "code": "RESOURCE_CONFLICT",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "REFRESH_STATE"
  },
  "errors": []
}

Related

• API Error Codes catalog
• RFC 9457 — Problem Details for HTTP APIs