Error Handling - Inklink Developer Documentation

Errors from the InkLink API use a shared JSON shape. All of them expect the api-key header (see Authentication).

HTTP status codes

Status	Typical meaning	What to do
200	Success	Parse the JSON body
400	Validation failed (`VALIDATION_ERROR`)	Fix the request using `error.details`
401	Not authenticated (`UNAUTHORIZED`)	Send a valid `api-key`
404	Resource missing (`NOT_FOUND`)	Check `id` belongs to your org and exists
429	Rate or usage limit (`RATE_LIMIT_EXCEEDED`)	Retry with backoff; check quotas
500	Server error (`INTERNAL_ERROR`)	Retry with backoff; If the issue persists, contact support

Error response format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": [
      { "field": "subject_id", "message": "String must contain at least 1 character(s)" }
    ],
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

code - Machine-readable enum (see below).
message - Short description for logging or UI.
details - Array of { "field", "message" }. Root-level validation messages may use an empty field ("").
requestId - Correlates with the x-request-id response header; use it with support.

Error `code` values

`code`	HTTP	Description
`VALIDATION_ERROR`	400	Body or path input failed validation (see `details`)
`UNAUTHORIZED`	401	Invalid or missing `api-key` (or no session, for dashboard-internal calls)
`NOT_FOUND`	404	Inquiry or result not found for your organization (e.g. wrong `id` or not visible to your org)
`RATE_LIMIT_EXCEEDED`	429	API key verification or org usage hit a rate or quota limit (`message` may include provider text)
`INTERNAL_ERROR`	500	Unexpected failure or guarded server error (`message` may vary); unhandled exceptions return a generic message