Error codes

1099Policy uses conventional HTTP status codes to indicate the outcome of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with the request — a missing parameter, a failed validation, or a business rule that prevents the operation. Codes in the 5xx range indicate a problem on our side.

Every error response carries a machine-readable type and code. Branch on those, never on the message string — message wording can change at any time without notice, but a published code will not change without a deprecation period.

The error object

All errors return the same envelope. The param field is present only when the error can be attributed to a specific field in your request.

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "type":       "eligibility_error",
    "code":       "invalid_job_category_code",
    "message":    "No active coverage matches job category jc_rSwUqFfnvm.",
    "param":      "job_category",
    "doc_url":    "https://www.1099policy.com/docs/error-codes#invalid_job_category_code",
    "request_id": "req_8Kx2yQ4mNb"
  }
}

Error types

Every code belongs to exactly one type. If you handle nothing else, handle these six — they tell you what kind of fix is required.

Error code reference

Codes are grouped by the resource you are working with. Each entry is anchor-linked, so the doc_url in an error response points at the exact row.

Authentication and access

Requests and platform

Contractors

Entities

Jobs and job categories

Quotes

Policies

Assignments

Invoices

Certificates

Application and payment sessions

Webhooks

Eligibility reason codes

Reason codes are not error codes. They appear on a successful 200 response from the assignment eligibility check when the assignment is not eligible — that is, when the response body contains "result": false. There is no error envelope and no 4xx status.

Where an eligibility response would otherwise say only that no active policy was found, reason_code names the actual cause, so you can act on it without parsing the message.

{
  "result": false,
  "message": "The job category 'Skilled or Intermed Nursing Home' (jc_rSwUqFfnvm) is not
              available for automatic policy issuance in IL. Use a job category that is
              enabled in this state, or contact support to enable this one.",
  "approval_reason": null,
  "reason_code": "job_category_not_rated_in_state"
}

Two behaviours to handle:

• The reason_code key is optional. It is present only when a specific cause can be identified. On every other ineligible assignment the key is absent entirely, so read it defensively rather than assuming it exists.
• It applies to the general opt-in path. Assignments whose contractor has no completed general opt-in application for the work state return the standard eligibility message and no reason_code.

Changes to this page

Published codes are stable. When a code is renamed we return both the old and the new value for at least 90 days before retiring the old one, and note it here.