Errors can occur at different levels. Sometimes it's an authentication error, sometimes the request parameters are missing some required information and sometimes there's a bug. Interacting with an API, you're going to have to handle errors; this document outlines how Cargonizer behaves when an error occurs.
The first thing to check is the HTTP status code. If it's not in the 200 range (or a 302 redirect), you've got an unexpected result to deal with. Here are some of the status codes we use:
- 200: Your request was successful
- 201: The resource you sent was created
- 302: Redirect: Follow the 'Location' header to the next URL
- 400: Validation or other "user" error (i.e. your fault). Review the error messages to see what's wrong
- 401: Authentication error. Check that you've authenticated properly
- 402: Authorization error. Most likely, the sender ID is missing or incorrect
- 403: Error. Either the sender ID is missing or incorrect or you have reached the limit of your licence
- 404: The resource you're trying to reach can not be found. This can occur if you're requesting a resource that belongs to a different sender
- 500: An error occured. This is most likely caused by missing or invalid parameters or by sending offending characters in the xml (&,<,>,",' etc. Remember to escape them.). Sometimes it can also be caused by a bug at our side so please contact us if you can't find any reasons why this error occure.
- 502: Temporarily unavailable. This may happen during a deployment or configuration change. Wait a few seconds and try again.
In addition to the status code, there will be an error message. If you've requested to be informed with XML (url ends with ".xml"), the error messages will follow a common structure:
<errors> <info> ... </info> <error>Error 1</error> <error>Error 2</error> </errors>
That is, an <errors> element with one or more <error> elements containing an error description. In addition, an <info> element will be present with information to help debugging what's wrong. It can look something like this:
<errors> <info> <request-id>92bd1c0fb905197d165a515cf82f2a0f</request-id> <user> <id>5432</id> <username>Denne e-postadressen er beskyttet mot programmer som samler e-postadresser. Du må aktivere javaskript for å kunne se den.</username> </user> <managership> <id>4567</id> <sender> <id>7890</id> <name>Joe's Garage</name> </sender> </managership> </info> <error>Missing transport agreement</error> </errors>
Missing transport agreement
- You are trying to create a consignment on a transport agreement that's not active on the account of the api user.
Product not in transport agreement
- You are trying to create a consignment with a product identyfier that's not available in the api users account.
Services er ugyldig
- You are trying to add freight services that doesnt correspond with the product. Typically trying to add a service from one carrier to another.
500 Internal Server Error
- Check your xml. Are all your tags closed? Do you have any typos in the tags? This can also be caused by not escaping offending characters (Characters like &, <,>,",') in your data, causing a crash.
This action requires a sender to be specified
- Most likely you have an incorrect SenderID. You can verify your SenderID through profile.xml.
This action requires authentication
- Most likely your API key is wrong, please verify your api key with the account owner or run it through profile.xml to verify it's authenticity.