API Error Code Details

Every non-2xx response from the Field Nation API conforms to RFC 9457 — Problem Details for HTTP APIs and is served with Content-Type: application/problem+json. The type field on every error is a resolvable URL into the catalog below.

Each error code has a dedicated page at /error-codes/<slug>/ and an anchored section on this page — jump straight to a section via the catalog table, or follow the dedicated-page link for sharable URLs.

The shape

Agent actions

Every error carries an agent.action so autonomous integrations can react without parsing prose. The vocabulary is closed and mirrors the AgentDecision.AgentAction enum in the upstream contract (proto/common/v1/problem_detail.proto).

Canonical example

{
  "type": "https://developer.fieldnation.com/error-codes/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while loading the work classifications catalog.",
  "code": "INTERNAL_SERVER_ERROR",
  "retryable": true,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "RETRY",
    "backoffMs": 1000,
    "maxAttempts": 4
  },
  "errors": []
}

Catalog

How to consume

• Branch on code, not on title or detail. code is contract-stable; the strings are not.
• Follow type in a browser to land directly on the docs for that error.
• Iterate errors[] when handling validation responses — each entry names a field and reason. The field is always present; when there are no sub-errors it's an empty array [].

Validation Error

The request was well-formed but one or more fields failed validation.

When it is returned

• A required field was missing or empty.
• A field value violated a format, range, or enum constraint.
• A business rule rejected the combination of submitted values.

Troubleshooting

• Inspect the errors[] array — each entry names the offending field and reason.
• Compare the request payload against the endpoint's OpenAPI schema in the playground.
• Fix the listed fields and resubmit.

Example response

HTTP/1.1 400 Validation Error
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "code": "VALIDATION_ERROR",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "FIX_INPUT"
  },
  "errors": [
    {
      "detail": "title is required.",
      "pointer": "/title"
    },
    {
      "detail": "assignee.id must be a positive integer.",
      "pointer": "/assignee/id"
    },
    {
      "detail": "pageSize must be between 1 and 100.",
      "parameter": "pageSize"
    }
  ]
}

Authentication Required

The request did not include valid authentication credentials.

When it is returned

• The Authorization header / access_token parameter was missing.
• The access token expired (tokens are valid for one hour).
• The token signature was invalid or revoked.

Troubleshooting

• Generate a fresh access token via the OAuth 2.0 flow.
• Confirm the token is sent on every request (header or query parameter).
• Implement token refresh ahead of the one-hour expiry.

Example response

HTTP/1.1 401 Authentication Required
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "The provided access token has expired.",
  "code": "AUTHENTICATION_REQUIRED",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "REAUTHENTICATE"
  },
  "errors": []
}

Insufficient Permissions

The caller is authenticated but not authorized for the requested resource or action — whether by role/scope, ownership, or a system-level rule.

When it is returned

• The API user lacks the role or scope required by the endpoint.
• The request targets a resource owned by another company.
• The action is gated by a feature flag, contract setting, or compliance constraint.
• The target resource is system-managed and the requested action is disallowed (e.g., editing a default task).

Troubleshooting

• Confirm the API user's role with your Field Nation administrator.
• Verify the resource belongs to the calling company.
• Review the endpoint's documented constraints for system-managed resources.
• If a missing entitlement is suspected, contact Field Nation support.

Example response

HTTP/1.1 403 Insufficient Permissions
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "The authenticated user does not have permission to publish work orders.",
  "code": "INSUFFICIENT_PERMISSIONS",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "ESCALATE"
  },
  "errors": []
}

Resource Not Found

The requested resource does not exist or is not visible to the caller.

When it is returned

• The identifier in the URL refers to a deleted or never-existing resource.
• The caller cannot see the resource due to scoping rules.
• The request hit the wrong environment (sandbox vs production).

Troubleshooting

• Re-verify the resource ID against the source of truth.
• Confirm you are calling the correct environment (api.fieldnation.com vs api-sandbox.fndev.net).
• List the parent collection to see which IDs are visible to your user.

Example response

HTTP/1.1 404 Resource Not Found
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Work order 12412546 was not found.",
  "code": "RESOURCE_NOT_FOUND",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "FIX_INPUT"
  },
  "errors": []
}

Resource Conflict

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": []
}

File Size Exceeded

The uploaded file exceeds the maximum allowed size for this endpoint.

When it is returned

• The file body is larger than the documented per-endpoint limit.
• A multipart upload's combined parts exceed the limit.

Troubleshooting

• Check the endpoint's documented size limit and compare against your file.
• Compress, resize, or split the file before retrying.
• For large client documents, use the dedicated large-upload flow if available.

Example response

HTTP/1.1 413 File Size Exceeded
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/file-size-exceeded",
  "title": "File Size Exceeded",
  "status": 413,
  "detail": "The uploaded file exceeds the maximum allowed size.",
  "code": "FILE_SIZE_EXCEEDED",
  "retryable": false,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "FIX_INPUT"
  },
  "errors": []
}

Rate Limit Exceeded

The caller has exceeded the API rate limit for this window.

When it is returned

• Sustained request volume exceeded the per-minute or per-hour quota.
• A burst saturated the short-term token bucket.
• Multiple integrations share the same API user and credentials.

Troubleshooting

• Honor the Retry-After response header before resubmitting.
• Implement exponential backoff plus jitter in retry logic.
• Track X-RateLimit-Remaining and throttle proactively.
• For high-volume integrations, request a higher quota from Field Nation.

Example response

HTTP/1.1 429 Rate Limit Exceeded
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryable": true,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "RETRY",
    "backoffMs": 60000,
    "maxAttempts": 3
  },
  "errors": []
}

Internal Server Error

An unexpected error occurred on Field Nation's servers.

When it is returned

• An unhandled exception was raised while processing the request.
• A downstream service (database, search index, queue) was unreachable.
• A bug surfaced an unexpected code path.

Troubleshooting

• Retry idempotent requests with exponential backoff (1s, 2s, 4s, 8s).
• Check status.fieldnation.com for ongoing incidents.
• If the problem persists, capture the detail value and the response timestamp, then contact support.

Example response

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while loading the work classifications catalog.",
  "code": "INTERNAL_SERVER_ERROR",
  "retryable": true,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "RETRY",
    "backoffMs": 1000,
    "maxAttempts": 4
  },
  "errors": []
}

Service Unavailable

The Field Nation API is temporarily unavailable.

When it is returned

• A downstream service (database, search index, queue) is temporarily unreachable.
• The API is undergoing maintenance or deployment.
• The system is experiencing degraded capacity.

Troubleshooting

• Honor the Retry-After response header before resubmitting.
• Implement exponential backoff plus jitter in retry logic.
• Check status.fieldnation.com for ongoing incidents.
• If the problem persists beyond the expected maintenance window, contact support.

Example response

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "https://developer.fieldnation.com/error-codes/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The service is temporarily unavailable. Please try again later.",
  "code": "SERVICE_UNAVAILABLE",
  "retryable": true,
  "correlationId": "01J9X7Q3F6E2K8B1Z5C4M0V2HA",
  "agent": {
    "action": "RETRY",
    "backoffMs": 5000,
    "maxAttempts": 3
  },
  "errors": []
}