PurpleTRAC API errors and status codes

PurpleTRAC does not return one error envelope. Different endpoints return different shapes, some responses are plain text, and a few are empty. Handle the status code first and treat the body as best-effort detail.

If you also build against Insights, note that the two products disagree on what 403 means. Here it says the feature is not enabled for your account.

Status codes

Code	Means
`400`	Invalid parameters, filtering or ordering on a field that does not allow it, malformed body, or a missing required field
`401`	Credentials missing or wrong. See Authentication
`403`	Almost always: the endpoint needs an optional feature that is not enabled for your account. `PUT /transaction/{id}/voyage_update` is the exception, where it means the transaction belongs to a different account
`404`	The transaction or resource does not exist
`405`	That method is not supported on that endpoint
`409`	A duplicate transaction already exists
`500`	System failure, a missing critical field, or a report that is not ready yet

403 does not always mean the same thing

On nearly every endpoint a 403 says the feature behind it is an addon your account does not
have. On PUT /transaction/{id}/voyage_update it says the transaction belongs to another
account. If you handle the two cases differently, branch on the endpoint as well as the code.

The response shapes you will meet

Four shapes cover almost everything.

Single message

Field errors

Coded error

Plain text or empty

{
  "error": "The 'test' field does not allow filtering."
}

Parse defensively. A client that assumes JSON will throw on the plain-text and empty responses.

General errors

Filtering on a field that does not allow it

GET /purpletrac/v1/<resource>?test=value returns 400.

{
  "error": "The 'test' field does not allow filtering."
}

PurpleTRAC rejects unknown filter parameters rather than ignoring them, so a typo fails the whole request.

Ordering on a field that does not allow it

GET /purpletrac/v1/<resource>?order_by=test returns 400.

{
  "error": "No matching 'test' field for ordering on."
}

Method not allowed

405, with a plain-text body naming the methods.

GET/POST/PUT/PATCH/DELETE not allowed

Vessel search

Upstream service unavailable

GET /purpletrac/v1/sisship returns 500 with a plain-text body when the ship information service behind it is down.

error while fetching ships from SIS

Retry with a backoff. Nothing about the request needs changing.

Screening

Body is not JSON

POST /purpletrac/v1/registration returns 400.

{
  "error": "Request is not valid JSON."
}

Too many additional entities

POST /purpletrac/v1/registration returns 400 when the request carries more than ten.

{
  "error": {
    "additional_entities": "Field cannot be bigger than 10 entities."
  }
}

Missing registered name

POST /purpletrac/v1/registration returns 500, not 400, when registered_name is absent. The body names the field.

{
  "error_message": "registered_name"
}

Transactions

Missing required fields

PUT /purpletrac/v1/transaction/{id} returns 400.

{
  "transaction": {
    "__all__": "Please add all required fields and values."
  }
}

Transaction not found

GET /purpletrac/v1/transaction/{id} returns 404 with an empty body. There is nothing to parse, so branch on the status code.

Duplicate transaction

PUT /purpletrac/v1/transaction/{id}/track returns 409 when the same entity is already tracked.

{
  "error_code": "DUPLICATE_FOUND",
  "error_info": {
    "type": "SAME_USER",
    "users": ["Demo Trader"]
  },
  "error_message": "Duplicate entry found"
}

error_info.type distinguishes a duplicate you created from one created by someone else on your account.

Additional entities during tracking

These apply to GET, PUT and DELETE on /purpletrac/v1/transaction/{id}/additional_entity. Managing Additional Entities has the workflow.

The same condition reports two different codes

A transaction that cannot be found is a 404 on GET and a 400 on PUT and DELETE. Match on both if you are handling one condition.

403, feature not enabled

404 on GET, transaction not found

400 on PUT and DELETE, transaction not found

400, transaction not tracking

400, no entities supplied

400, entity cap exceeded

400, duplicates in the request

400, entity already added

400, invalid entity payload

400 on DELETE, no ids supplied

400 on DELETE, entity not found or already removed

Reports

Invalid parameters

GET /purpletrac/v1/screening_report?transaction_id=test returns 400 with a plain-text body.

Invalid report params: * transaction_id * Enter a whole number.

Report not ready

A report that has not finished generating returns 500 with an empty body. Retry after a short wait rather than treating it as a failure.

Authentication

What 401 and 403 each tell you about your credentials and your account.

Getting Started

The transaction id, and which addons your account configuration gates.

FAQ

Why screening can run long, and when to archive.

PurpleTRAC Errors and Status Codes

Status codes#

The response shapes you will meet#

General errors#

Filtering on a field that does not allow it#

Ordering on a field that does not allow it#

Method not allowed#

Vessel search#

Upstream service unavailable#

Screening#

Body is not JSON#

Too many additional entities#

Missing registered name#

Transactions#

Missing required fields#

Transaction not found#

Duplicate transaction#

Additional entities during tracking#

Reports#

Invalid parameters#

Report not ready#

Related#