Error Codes

Documentation Index

Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• HTTP status code — coarse category (auth, permissions, validation, server)
• errors[] payload in the response body — specific message, often pointing directly at the fix

{
  "errors": [
    {
      "message": "User does not have permission to update this resource."
    }
  ]
}

​

HTTP status reference

​

401 Unauthorized

• No Authorization header
• Expired token
• Wrong audience or issuer (token from one auth provider, ION expecting another)
• Token belongs to a different organization than the user

​

403 Forbidden

Rule of thumb: If a 403 says “permission” → check the user’s role. If it says “not found” or refers to an ID → check the entity’s tenant. If it says “read-only” → check the org’s billing/compliance state.

​

Sample 403 payload

{
  "errors": [
    {
      "message": "User does not have permission to perform UPDATE on Purchase Order."
    }
  ]
}

​

404 Not Found

• ID typo
• Entity was soft-deleted (most ION entities use the _deleted flag rather than hard-delete)
• Cross-tenant ID (see 403 above — sometimes this surfaces as 404 instead, depending on the resolver)

​

409 Concurrency Conflict

{
  "errors": [
    { "message": "Concurrent modification detected — etag mismatch." }
  ]
}

1. Re-read the entity to get the latest _etag (and the latest field values)
2. Re-apply your changes on top of the new state
3. Retry the mutation with the new _etag

​

422 Validation Error

• Quantity ≤ 0
• Required field missing
• Date out of range
• String too long for the column
• Enum value not allowed

{
  "errors": [
    { "message": "PartInventory quantity must be greater than 0." }
  ]
}

​

429 Rate Limit

1. Implement exponential backoff in your client (start at 1s, double up to ~30s, jitter)
2. Batch related queries — one query selecting many fragments beats N queries each selecting one fragment
3. Cache locally — for data that doesn’t change often (parts, procedures), don’t re-fetch every time

​

5xx Server Errors

HTTP/1.1 502 Bad Gateway

1. Retry with exponential backoff (1s, 2s, 4s, 8s…)
2. After 3 consecutive failures across ~30s, surface to the user / on-call
3. Check ION’s status page if available, or contact support if persistent

​

GraphQL errors[] shape

{
  "data": null,
  "errors": [
    {
      "message": "User does not have permission to perform UPDATE on Purchase Order.",
      "path": ["updatePurchaseOrder"],
      "locations": [{ "line": 2, "column": 3 }]
    }
  ]
}

​

Troubleshooting flow

1. Check the HTTP status.
2. If 200, parse errors[] from the response body.
3. Match the message against the tables on this page.
4. If unfamiliar, the message wording usually points at the offending field/permission/resource — search for it in the Authentication and this page’s tables.
5. Still stuck → reproduce the call in the API Playground (which surfaces errors more readably) and paste the request + error into a support ticket.

​

Tips

• Log the full response body, not just the status code. The errors[] payload is where remediation actually lives.
• Don’t retry 4xx errors blindly — they won’t fix themselves. Only 429 and 5xx are safe to retry without changing inputs.
• Treat 403 as an admin action, not a code change. The most common “fix” for 403 is a role grant, not a code update.
• Surface concurrency 409s to humans when relevant — letting an operator see “this was modified by Alice 30 seconds ago” prevents bad merges.

​

Related

• Authentication — full 401 reference
• GraphQL Field Selection — explains why “everything looks blank” isn’t usually an error
• API Playground — interactive error reproduction