This page covers what an OSF receives when using the REST API in pull mode — submitting a request, then calling GET endpoints to check its status. This is the model used by our Postman collections.

There are two situations, with two different response shapes.

A. Synchronous validation errors (the request itself was rejected)

Returned immediately, on the call that submits the request (e.g. POST /requests/registrations, POST /requests/retrievals, POST /requests/files/url-uploads), when the input is malformed, mismatched, or unauthorized. HTTP status is 4xx.

Example request:

POST /requests/registrations
{
  "operationCategory": "registration",
  "documentKindCategory": "patent",
  "documentNumber": "IB PCT/IB2026/098496",
  "documentDate": "2026-02-08",
  "dasAccessCode": "1234",
  "email": "jjduffy@example.com",
  "fileId": "US-bf5f35ff-2a94-4082-8c1c-02e321178232"
}

Example response (HTTP 400):

{
  "code": "INVALID_INPUT_DATA",
  "message": "Invalid input data or document",
  "details": [
    { "code": -4, "message": "Mismatched access code: dasAccessCode: expected dasAccessCode=AB46" }
  ]
}

code is the error category (SUCCESS, INVALID_INPUT_DATA, OPERATION_FORBIDDEN, DAS_SYSTEM_ERROR, OPERATION_IN_PROGRESS, INVALID_TOKEN). details[] lists one or more specific reasons.

Message you will receive, per situation

Note: when the access code you supplied is incorrect, the response will not reveal the correct value, for security reasons — you will only see the field name, not the "expected" value.

B. Asynchronous status polling (the request was accepted; you're checking what happened to it)

Covers GET .../requests/retrievals/statuses, GET .../requests/registrations (record), and the bulk recorded-requests list. These return HTTP 200 even when the underlying operation failed or is still pending — the result is only visible in the body, via requestStatusCategory and requestStatusMessage. There is no numeric error code on this channel.

Example request:

GET /requests/retrievals/statuses?requestAckId=USIB20260101010101

Example response — pending:

{
  "requestAckId": "USIB20260101010101",
  "requestStatusCategory": "pending",
  "requestStatusMessage": "awaiting off response"
}

Example response — error:

{
  "requestAckId": "USIB20260101010101",
  "requestStatusCategory": "error",
  "requestStatusMessage": "unmatched access code"
}

Values you may see (retrieval)

Values you may see (registration)

Retrieval failures from a hosted OFF: legacy TDA/PDX code vs. the message you will actually receive

When the failure comes from a hosted Office of First Filing, the requestStatusMessage you see on this poll depends on which protocol that office uses to answer. The table below matches each legacy TDA/PDX code to the message you receive today (office still on TDA/PDX) and the message you can expect once that office migrates to the newer REST interface (see 5.1.1.- Responses from OFF to DAS (TDA/PDX codes) for the full legacy-code reference, and 5.1.2.- Responses from DAS to OSF via notification endpoint for the equivalent on the push-notification channel).

Quick reference