Error Codes

When working with the Visiwise API, you might encounter different error responses. This guide explains what each error code means and shows you what the response looks like.

All error responses follow the same format, making it easy to handle them in your code:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [
      {
        "code": "ERROR_CODE",
        "target": "Field name",
        "message": "Human-readable error message",
        "suggested_fix": "Human-readable suggested fix message"
      }
    ]
  },
  "data": null
}

Common HTTP Error Codes

400 Bad Request

This happens when your request isn't formatted correctly or contains invalid data.

Example response:

{
  "error": {
    "code": "invalid_input",
    "message": "Invalid input",
    "details": [
      {
        "code": "uuid_parsing",
        "target": "id",
        "message": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3",
        "suggested_fix": "Please provide a valid value for this field."
      }
    ]
  },
  "data": null
}

401 Unauthorized

This means your API key is missing, invalid, or has been revoked.

Example response:

{
  "error": {
    "code": "authentication_error",
    "message": "Authentication error",
    "details": [
      {
        "code": "INVALID_API_KEY",
        "target": "api_key",
        "message": "Invalid API key.",
        "suggested_fix": "Please provide a valid API key."
      }
    ]
  },
  "data": null
}

403 Forbidden

Your API key is valid, but you don't have permission to perform this action.

Example response:

{
  "error": {
    "code": "authorization_error",
    "message": "Authorization error",
    "details": [
      {
        "code": "INVALID_USER",
        "target": "user",
        "message": "User is inactive or deleted.",
        "suggested_fix": "Please contact support."
      }
    ]
  },
  "data": null
}

404 Not Found

The resource you're looking for doesn't exist.

Example response:

{
  "error": {
    "code": "not_found",
    "message": "Not found",
    "details": []
  },
  "data": null
}

429 Too Many Requests

You've hit our rate limits. Please wait before making more requests.

Example response:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limited",
    "details": []
  },
  "data": null
}

500 Internal Server Error

Something went wrong on our end. This is usually temporary.

Example response:

{
  "error": {
    "code": "server_error",
    "message": "Server error",
    "details": []
  },
  "data": null
}

What to Do When You Get an Error

1. Check your API key - Make sure it's correct and hasn't expired
2. Verify your request - Double-check the URL and parameters
3. Wait if rate limited - Wait for a while and try again
4. Try again later - For server errors, wait a bit and retry
5. Contact support - If the problem persists, reach out to our team