DOCSEARCHbyAlgolia
Submit Docs

Field Nation API Error Codes

website·Indexed 35 days ago

https://developer.fieldnation.com/

Documentation of the RFC 9457 Problem Details catalog for the Field Nation API. Includes detailed explanations for non-2xx responses such as Rate Limit Exceeded, Authentication Required, Resource Not Found, and Validation Errors.

Tokens
4.9K
Snippets
15
Records
21
Agent score
58%

What's inside Field Nation

  1. Troubleshoot authorization failures in Field Nation API

    When receiving a 403 Insufficient Permissions error, follow these steps to resolve the issue:

    1. Verify Roles: Confirm the API user's assigned role with your Field Nation administrator.
    2. Check Ownership: Ensure the resource being requested belongs to the calling company.
    3. Review Constraints: Check the API documentation for the specific endpoint to see if the resource is system-managed or has specific constraints.
    4. Contact Support: If you suspect a missing entitlement or contract setting is causing the block, contact Field Nation support.

  2. Resolve Field Nation API authentication failures

    To resolve AUTHENTICATION_REQUIRED errors, follow these steps:

    1. Generate a fresh access token using the OAuth 2.0 flow.
    2. Ensure the token is included in every request via the Authorization header or as a query parameter.
    3. Implement a token refresh mechanism to replace tokens before they expire (expiry is one hour).

  3. Handle API errors using Agent Actions

    The Field Nation API provides an agent.action field in error responses to allow autonomous integrations to react without parsing text.

    ActionMeaningTypical HTTP Status
    FIX_INPUTRequest is invalid. Correct input before retrying.400, 404
    RETRYRetry the same request after agent.backoffMs (or Retry-After header).429, 503
    REFRESH_STATERe-read current resource state, reconcile conflict, then resend.409
    REAUTHENTICATEObtain fresh credentials, then resend.401
    ESCALATESurface to a human operator; automated retry will fail.403, Policy Violations

  4. Resolve Resource Conflict based on agent action

    Depending on the agent.action returned in the 409 error response, follow these resolution steps:

    1. REFRESH_STATE (Data conflict / concurrent edit): A unique constraint was violated or the resource was modified by another process.

      • Action: Re-read the resource to inspect the current state, reconcile the conflict (e.g., rename or merge edits), and retry. For optimistic-concurrency endpoints, refresh the version or etag before resubmitting.

    2. FIX_INPUT (Illegal state transition): The resource is in a state that disallows the requested action (e.g., completing a work order that is currently under review).

      • Action: Inspect the resource's current status and compare it against documented allowed transitions. The detail field in the error response describes the specific rule violated. Re-fetching the state will not resolve this; the request input must be changed.

  5. Handle Authentication Required errors (401)

    An AUTHENTICATION_REQUIRED (HTTP 401) error indicates missing, expired, or invalid credentials. Access tokens are valid for one hour.

    Troubleshooting:

    • Generate a new access token via the OAuth 2.0 flow.
    • Ensure the token is included in the Authorization header or as an access_token query parameter on every request.
    • Implement a token refresh mechanism to trigger before the one-hour expiry. The agent.action will be REAUTHENTICATE and retryable will be false.
    {
  "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": []
}

  6. Handle RESOURCE_NOT_FOUND (404) errors

    The RESOURCE_NOT_FOUND error indicates that the requested resource does not exist or is not visible to the caller. This typically happens if the ID is incorrect, the resource was deleted, the caller is restricted by scoping rules, or the request was sent to the wrong environment (e.g., sandbox vs production).

    Troubleshooting steps:

    • Re-verify the resource ID against the source of truth.
    • Confirm the correct environment URL is being used (api.fieldnation.com for production vs api-sandbox.fndev.net for sandbox).
    • List the parent collection to verify which IDs are visible to the current user.
    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": []
}

  7. Handle Field Nation API 503 Service Unavailable errors

    The SERVICE_UNAVAILABLE error (HTTP 503) indicates that the Field Nation API is temporarily unavailable. This typically occurs when a downstream service (database, search index, or queue) is unreachable, during system maintenance/deployment, or when the system is experiencing degraded capacity.

    Recommended Actions:

    • Honor the Retry-After response header before resubmitting the request.
    • Implement exponential backoff with jitter in your retry logic.
    • Check status.fieldnation.com for ongoing incidents.
    • Contact support if the issue persists beyond a maintenance window.

    Retry Specifications:

    • Retryable: Yes
    • Suggested Action: RETRY
    • Suggested Backoff: 5000 ms
    • Max Attempts: 3
    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": []
}

  8. Internal Server Error response specification

    The INTERNAL_SERVER_ERROR response uses the application/problem+json content type. It includes a correlationId for support tracking and an agent object providing specific retry guidance.
    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": []
}

  9. Handle Validation Errors (400)

    A VALIDATION_ERROR (HTTP 400) occurs when a request is well-formed but fails business rules, format constraints, or is missing required fields.

    Troubleshooting:

    • Iterate through the errors[] array to identify the specific offending fields and reasons.
    • Compare the payload against the OpenAPI schema in the playground.
    • Correct the identified fields and resubmit. The agent.action will be FIX_INPUT and retryable will be false.
    {
  "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"
    }
  ]
}

  10. Handle RESOURCE_CONFLICT (409) errors

    The RESOURCE_CONFLICT error occurs when a request conflicts with the current state of a resource. There are two primary scenarios:

    1. Data Conflict / Concurrent Edit (agent.action: REFRESH_STATE): A uniqueness violation occurred or the resource was modified by another process. Resolve this by re-reading the resource, reconciling changes, and retrying.
    2. Illegal State Transition (agent.action: FIX_INPUT): The resource is in a state that prohibits the requested action (e.g., completing a work order that is currently under review). Re-fetching the state will not fix this; the input parameters must be changed.

    Troubleshooting steps:

    • For data conflicts: Re-read the resource to inspect current state and reconcile edits.
    • For state transitions: Check the resource's current status against documented allowed transitions and review the detail field in the response.
    • For optimistic-concurrency endpoints: Refresh the version or etag before resubmitting.

  11. Understand the Field Nation API error response format

    All non-2xx responses from the Field Nation API conform to RFC 9457 (Problem Details for HTTP APIs) and use the Content-Type: application/problem+json. Developers should branch logic based on the code field rather than title or detail, as code is contract-stable.

    Response Properties:

    • type (URI): Resolvable URL identifying the error type.
    • title (string): Short, human-readable summary.
    • status (integer): HTTP status code.
    • detail (string): Occurrence-specific explanation.
    • code (UPPER_SNAKE): Machine-readable, stable error code.
    • errors (array): Sub-errors for compound errors (e.g., validation details). Always present.
    • retryable (boolean): Indicates if the exact same request can be safely retried.
    • correlationId (string): Unique ID for the request; provide this when contacting support.
    • agent (object): Contains action (required), and optionally backoffMs and maxAttempts if the action is RETRY.
    {
  "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": []
}

  12. Handle Field Nation API Validation Errors (VALIDATION_ERROR)

    A VALIDATION_ERROR occurs when a request is syntactically well-formed but contains data that fails business or format validation. This error is non-retryable (retryable: false) and requires the client to fix the input (agent.action: FIX_INPUT) before resubmitting.

    Common causes include:

    • Missing or empty required fields.
    • Values violating format, range, or enum constraints.
    • Combinations of values that violate business rules.

    To resolve this error:

    1. Inspect the errors[] array in the response body to identify the offending fields and the specific reason for failure.
    2. Compare the request payload against the endpoint's OpenAPI schema.
    3. Correct the identified fields and resubmit the request.
    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"
    }
  ]
}