Error Handling

Learn how to handle API errors gracefully and troubleshoot common issues.

HTTP Status Codes

The Konver API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Status Code	Description
200 OK	Request succeeded
201 Created	Resource was successfully created
204 No Content	Request succeeded with no response body

Client Error Codes

Status Code	Description
400 Bad Request	Invalid request syntax or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid API key but insufficient permissions
404 Not Found	Requested resource doesn't exist
422 Unprocessable Entity	Request validation failed
429 Too Many Requests	Rate limit exceeded

Server Error Codes

Status Code	Description
500 Internal Server Error	Something went wrong on our end
502 Bad Gateway	Upstream service error
503 Service Unavailable	Service temporarily unavailable

Error Response Format

The API uses standard HTTP status codes to indicate errors. A 404 Not Found response is returned when a resource doesn't exist.

note

The exact error response format may vary. Always check the HTTP status code first when handling errors.

Troubleshooting

Authentication Issues

Problem: Receiving 401 Unauthorized errors

Solutions:

1. Verify your API key is correct
2. Check that the Authorization header format is Bearer YOUR_API_KEY
3. Ensure there are no extra spaces or newlines in the key
4. Confirm the API key hasn't been revoked

Resource Not Found

Problem: Receiving 404 Not Found errors

Solutions:

1. Verify the resource ID is correct (should be a valid UUID)
2. Confirm the resource exists and hasn't been deleted
3. Check that you're using the correct API endpoint

Rate Limiting

Problem: Receiving 429 Too Many Requests errors

Solutions:

1. Implement request throttling in your application
2. Use exponential backoff for retries
3. Cache responses where appropriate
4. Contact support if you need higher rate limits

See the Rate Limiting Guide for more details.

Debugging Tips

1. Log request details: Include the endpoint, headers (minus the API key), and request body
2. Check response headers: They often contain useful debugging information
3. Use the API explorer: Test endpoints directly in the API Reference
4. Review webhook delivery logs: Check for patterns in failures

Getting Help

If you're experiencing persistent issues:

1. Review the error response details for specific guidance
2. Contact support at support@konver.ai with:
   • The error code and message
   • The endpoint you're calling
   • A timestamp of when the error occurred
   • Your organization (not your API key)

Next Steps

Once you understand how to handle errors, you're ready for the next steps:

• Rate Limiting — Understand API rate limits
• Webhooks — Set up real-time event notifications
• API Reference — Complete API documentation