Skip to main content
Retrac API returns machine readable error codes, human readable error messages and a link to the docs for more information. Here is how an error response looks like: 
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.retrac.co/api-reference/errors#not-found"
  }
}

​
Error Codes

Here is a list of all error codes Retrac API returns:

​
bad_request

  • Status: 400
  • Problem: The request is malformed, either missing required fields, using wrong datatypes, or being syntactically incorrect.
  • Solution: Check the request and make sure it is properly formatted.

​
unauthorized

  • Status: 401
  • Problem: The request has not been applied because it lacks valid authentication credentials for the target resource.
  • Solution: Make sure you are using the correct API key or access token.

​
forbidden

  • Status: 403
  • Problem: The server understood the request, but refuses to fulfill it — insufficient API scope, workspace role, location access, or plan.
  • Solution: Verify your API key scopes, user role, and workspace plan. Use a key with the required scope (e.g. inventory.write).

​
exceeded_limit

  • Status: 403
  • Problem: The workspace hit a plan limit (items, transfers, locations, tags, or users).
  • Solution: Upgrade the workspace plan or reduce usage before retrying.

​
invite_pending

  • Status: 409
  • Problem: The authenticated user has a pending workspace invite but has not accepted it yet.
  • Solution: Accept the workspace invite in the dashboard, then retry.

​
not_found

  • Status: 404
  • Problem: The server has not found anything matching the request URI.
  • Solution: Check the request and make sure the resource exists.

​
conflict

  • Status: 409
  • Problem: Another resource already uses the same identifier. For example, workspace slug must be unique.
  • Solution: Change the identifier to a unique value.

​
invite_expired

  • Status: 410
  • Problem: The invite has expired.
  • Solution: Generate a new invite.

​
unprocessable_entity

  • Status: 422
  • Problem: The server was unable to process the request because it contains invalid data.
  • Solution: Check the request and make sure input data is valid.

​
rate_limit_exceeded

  • Status: 429
  • Problem: The request has been rate limited.
  • Solution: Wait for a while and try again.

​
internal_server_error

  • Status: 500
  • Problem: The server encountered an unexpected condition that prevented it from fulfilling the request.
  • Solution: Try again later. If the problem persists, contact support.