Supply Lens

Troubleshooting File Drop

Lesson 25 of 28 6 min read

Read File Drop's status codes and error details, and work through the checklist when a partner says their upload failed.

When a partner says "our upload failed", the response they received usually says exactly why. This lesson teaches you to read it, and gives you a checklist for when it doesn't.

Read the problem body

When File Drop rejects a request it returns a problem body (application/problem+json). The detail value gives the cause:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The integration type does not support file drop"
}

What each error means

  • 201Accepted. The file was kept as source data. Check the conversion in the app.
  • 400 Incorrect integration typeNo enabled, installed Integration of this type in the organisation, or the value is wrong (it is case-sensitive). Check the value, then speak to Supply Lens.
  • 400 Does not support file dropFile Drop is not enabled for this integration type. Speak to Supply Lens.
  • 400 Too many integrationsTwo or more enabled Integrations of this type. Speak to Supply Lens.
  • 400 DuplicateA file with this external id was received before. Don't send it again.
  • 400 Problem saving the fileThe file was not kept. Send it again; if it repeats, speak to Supply Lens.
  • 400 ValidationA required value is missing or invalid. The errors object names it.
  • 401Token missing, expired or invalid. Get a new token.
  • 403Token lacks file_drop:write, was not issued for this organisation, or the organisation has no active subscription.
  • 404Wrong URL. Check both path values and that the organisation id is a GUID.
  • 413Request larger than 1 MB.
  • 415Content-Type is neither application/json nor multipart/form-data.
  • 500 Invalid document typeThe type value is not a known Document type. Correct it before retrying.

An unknown type returns 500, not 400

Today an unknown type causes a 500. It looks like a server fault but is not: retrying without a change will fail the same way. Correct the type value first.

Reading the token

The token is a JSON Web Token (JWT). You don't normally need to read it, but for a 403 its claims tell you why:

audMust contain integrations.
scopeMust contain file_drop:write.
organisationIdMust contain the organisation id used in the URL. There is one claim for each organisation the client can send to.

The checklist

When the cause isn't obvious, work through these in order:

  1. Production addresses: id.supplylens.co.uk and filedrop.supplylens.co.uk.
  2. Authorization header is Bearer, one space, then the token.
  3. The token has not expired.
  4. The token has file_drop:write and the organisation id claim.
  5. The organisation id in the URL matches the claim.
  6. integrationTypeId is exactly the lowercase value Supply Lens gave.
  7. type is a lowercase value from the list.
  8. JSON form: type and reference in the query string, JSON body.
  9. Multipart form: type and file as form parts, and the file part has a file name.
  10. The request is under 1 MB.
  11. The same id has not been sent before.

When the upload worked but nothing happened

If the partner got 201 but no Document appeared, the problem is after File Drop. Open the source data page from the Location header and look at its logs. Keep the returned id: it is the identifier to give Supply Lens support if you need help with the file. A common cause is an Integration that is not configured to convert that Document type, which File Drop does not check.

The source data page shows the file as received, with Logs and Reprocess.

Sandpiper's 403 on day one

The 3PL's first upload returns 403 with no body. Sandpiper's implementer asks the developer to decode the token: scope contains file_drop:write, but the organisationId claim is a different GUID from the one in the URL. The developer had copied the organisation id from a test organisation. With the right id in the URL, the next upload returns 201.

Recap

  • The detail in the problem body names the cause of most failures.
  • 401 means get a new token; 403 means check the token's scope and organisation claims.
  • Integration type errors need Supply Lens to enable File Drop or fix the Integration count.
  • An unknown type returns 500: fix the value rather than retrying.
  • A 201 with no Document means look at the source data and the Integration's configuration.

Quick guides for this topic

Complete and continue

Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.

Sending a file to File DropHow print integrations work